# Build a Delta Order to Sign

## Build a Delta Order to Sign

<mark style="color:blue;">`POST`</mark> `https://api.paraswap.io/delta/orders/build`

This section explains how to construct a Delta Order, which is essential for executing trades using the Velora Delta API. The /orders/build endpoint retrieves a Delta price and allows fallback to market prices.

A successfully built order includes a structured object ready for signing.

Common errors include validation failures, unsupported assets, and signature mismatches.

Use this guide to generate a Delta Order and prepare it for signing before submission.

#### Request Body Parameters

<table><thead><tr><th width="170">Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>price<mark style="color:red;">*</mark></td><td>DeltaPrice</td><td>The <code>delta</code> object retrieved from <code>/quote</code> <a href="/pages/K690HWhFH6b7Yws9p0Sv#mode-delta-200-successful-response">endpoint</a>.</td></tr><tr><td>chainId<mark style="color:red;">*</mark></td><td>number</td><td>Chain ID. (Mainnet - 1, Optimism - 10, BSC - 56, Polygon - 137, Fantom - 250, zkEVM - 1101, Base - 8453, Arbitrum - 42161, Avalanche - 43114, Gnosis - 100).</td></tr><tr><td>owner<mark style="color:red;">*</mark></td><td>string</td><td>Order owner address.</td></tr><tr><td>bridge</td><td>DeltaBridge</td><td>Required only for cross-chain orders. See below for details</td></tr><tr><td>beneficiary</td><td>string</td><td>Order beneficiary. Default: <code>zero address</code>, meaning owner address.</td></tr><tr><td>slippage</td><td>number</td><td>Slippage in base points (<code>100</code> is <code>1%</code>). Default: <code>100</code>.</td></tr><tr><td>deadline</td><td>number</td><td>Order expiry time as UNIX timestamp. Default: 1 hour from order creation.</td></tr><tr><td>nonce</td><td>string</td><td>Arbitrary <code>uint256</code> value to be used as order <code>nonce</code>. Default: <code>value generated with internal algos</code>. It is recommended to omit this param.</td></tr><tr><td>permit</td><td>string</td><td>Encoded permit to be used in order settlement. Supported permit types are described <a href="#supported-permits">here</a>. Default: <code>0x</code>.</td></tr><tr><td>partiallyFillable</td><td>boolean</td><td>If <code>true</code>, order will be generated as partially fillable. Default: <code>false.</code> </td></tr><tr><td>partnerAddress</td><td>string</td><td>Address of the partner. Used to collect fees from the order. Default: <code>zero address</code>.</td></tr><tr><td>partnerFeeBps</td><td>number</td><td>Partner fee percent in base points (<code>100</code> is <code>1%</code>). Max value is <code>200</code>. Default: <code>0</code>. </td></tr><tr><td>partnerTakesSurplus</td><td>boolean</td><td>If <code>true</code>, partner will collect <code>50%</code> of the order surplus instead of flat percent fee. Default: <code>false</code>.</td></tr></tbody></table>

`DeltaBridge` structure:

| Name               | Type   | Description                                                                                                                                                                                                                                                                                   |
| ------------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| protocolSelector   | string | Selector that indicates the bridge protocol used. Obtained from the price API                                                                                                                                                                                                                 |
| destinationChainId | number | Destination chain ID. (Mainnet - 1, Optimism - 10, BSC - 56, Polygon - 137, Fantom - 250, zkEVM - 1101, Base - 8453, Arbitrum - 42161, Avalanche - 43114, Gnosis - 100).                                                                                                                      |
| outputToken        | string | Output token on the destination chain. List of supported output tokens can be obtained from `/bridge-info` [endpoint](/api/velora-api/velora-delta-api/retrieve-details-for-creating-cross-chain-order.md#get-bridge-info). Output token can also be obtained from `price.bridge.outputToken` |
| scalingFactor      | number | Specifies difference between the decimals in source bridge token and destination token                                                                                                                                                                                                        |
| protocolData       | string | Protocol-specific data, obtained from pricing API                                                                                                                                                                                                                                             |

{% tabs %}
{% tab title="200 Successful Response " %}

```json
{
  "toSign": {
    "domain": {
      "name": "Portikus",
      "version": "2.0.0",
      "chainId": 1,
      "verifyingContract": "0x0000000000bbf5c5fd284e657f01bd000933c96d"
    },
    "types": {
      "Order": [
        {
          "name": "owner",
          "type": "address"
        },
        {
          "name": "beneficiary",
          "type": "address"
        },
        {
          "name": "srcToken",
          "type": "address"
        },
        {
          "name": "destToken",
          "type": "address"
        },
        {
          "name": "srcAmount",
          "type": "uint256"
        },
        {
          "name": "destAmount",
          "type": "uint256"
        },
        {
          "name": "expectedAmount",
          "type": "uint256"
        },
        {
          "name": "deadline",
          "type": "uint256"
        },
        {
          "name": "kind",
          "type": "uint8"
        },
        {
          "name": "nonce",
          "type": "uint256"
        },
        {
          "name": "partnerAndFee",
          "type": "uint256"
        },
        {
          "name": "permit",
          "type": "bytes"
        },
        {
          "name": "metadata",
          "type": "bytes"
        },
        {
          "name": "bridge",
          "type": "Bridge"
        }
      ],
      "Bridge": [
        {
          "name": "protocolSelector",
          "type": "bytes4"
        },
        {
          "name": "destinationChainId",
          "type": "uint256"
        },
        {
          "name": "outputToken",
          "type": "address"
        },
        {
          "name": "scalingFactor",
          "type": "int8"
        },
        {
          "name": "protocolData",
          "type": "bytes"
        }
      ]
    },
    "value": {
      "owner": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "beneficiary": "0x0000000000000000000000000000000000000000",
      "srcToken": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "destToken": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "srcAmount": "10000000",
      "destAmount": "9127760",
      "expectedAmount": "9219960",
      "deadline": 1757333024,
      "kind": 0,
      "nonce": "47551995136396664604384293391986507799897145387152361812735887931703330715323",
      "permit": "0x",
      "partnerAndFee": "0",
      "metadata": "0x",
      "bridge": {
        "protocolSelector": "0x21eaa4cd",
        "destinationChainId": 8453,
        "outputToken": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
        "scalingFactor": 0,
        "protocolData": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000"
      }
    }
  }
}
```

{% endtab %}

{% tab title="400 Price Error" %}

```json
{
    "errorType": "InvalidHmac",
    "details": "Invalid HMAC"
}
```

{% endtab %}
{% endtabs %}

#### Most common error types&#x20;

* `ValidationError` - validation for params failed
* `UnsupportedChain` - the chain ID is not supported by Delta.
* `UnsupportedToken` - the token is not supported by Delta.
* `InvalidHmac` - `hmac` check failed, meaning `price` object returned from `/quote` endpoint was mutated.

### Supported Permits

* `Permit(ERC-2612)` - expected to have 224 bytes length (owner, spender, value, deadline, v, r, s).
* `Permit2`
  * `TransferFrom` format - expected length is 96 bytes (32 for permitNonce, 64 for compact signature), amount and deadline should be the same as in `Order.`
  * `Allowance` format - expected length is 192 bytes.
* `DAI Style Permit` - expected length is 256 bytes.
* `0x01` - special `permit` value that signifies existing `Permit2` allowance.

[Delta Contract](/api/velora-api/velora-delta-api/contracts.md) should be specified as a spender is a permit.

## Sign an Order

Once the Delta Order is built, it must be signed using the EIP-712 standard before submission. This section provides a working example using ethers.js and axios.

Example:

```typescript
import { ethers, TypedDataEncoder } from "ethers"; // ethers V6
import axios from "axios";

const userWallet = new ethers.Wallet(ethers.id("alice"));
const userAddress = userWallet.address;
const chainId = 1;
// fetch price
const { data: quoteData } = await axios.get("https://api.paraswap.io/quote?mode=delta&...");
const price = quoteData.delta;
// prepare build order params
const buildOrderParams = {
    price,
    owner: userAddress,
    chainId,
    partnerAddress: "0x81037e7be71bce9591de0c54bb485ad3e048b8de",
    partnerFeeBps: 100, // 1%
    partnerTakesSurplus: false, // the default
};
// build the order to sign
const { data: buildOrderData } = await axios.post("https://api.paraswap.io/delta/orders/build", buildOrderParams);
const { domain, types, value: order } = buildOrderData.toSign;
// hash the order
const eip712Hash = TypedDataEncoder.hash(
  domain,
  types,
  order,
);
// sign and compact
const signature = userWallet.signingKey.sign(typedHash).compactSerialized; // ERC-2098 representation
```

## Sign an order (cross-chain)

The following snippet provides an example implementation of constructing the `DeltaBridge` structure for the cross-chain swap

```typescript
import { ethers, TypedDataEncoder } from "ethers"; // ethers V6
import axios from "axios";

const ETH_ADDRESS = "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee"; // same across all chains
const USDC_ADDRESS_ETH = "0xA0b86991c6218b36c1d19D4a2e9EB0CE3606EB48"; // USDC on Ethereum
const WETH_ADDRESS_OP = "0x4200000000000000000000000000000000000006";

const userWallet = new ethers.Wallet(ethers.id("alice"));
const userAddress = userWallet.address;
const srcChainId = 1;
const destChainId = 10;


const buildAndSignOrder = async (
	srcToken: string,
	srcDecimals: number,
	// dest token on destination chain
	destToken: string,
	destDecimals: number,
	srcChainId: number,
	destChainId: number,
	amount: number,
) => {
	const { data: quoteData } = await axios.get(`https://api.paraswap.io/quote`, {
		params: {
			mode: "delta",
			srcToken,
			srcDecimals,
			destToken,
			destDecimals,
			chainId: srcChainId,
			destChainId,
			amount,
		},
	});

	const price = quoteData.delta;

	// prepare build order params
	const buildOrderParams = {
		price,
		owner: userAddress,
		chainId: srcChainId,
		partnerAddress: "0x81037e7be71bce9591de0c54bb485ad3e048b8de",
		partnerFeeBps: 100, // 1%
		partnerTakesSurplus: false, // the default,
		bridge: price.bridge,
	};
	// build the order to sign
	const { data: buildOrderData } = await axios.post(
		"https://api.paraswap.io/delta/orders/build",
		buildOrderParams,
	);
	const { domain, types, value: order } = buildOrderData.toSign;
	// hash the order
	const eip712Hash = TypedDataEncoder.hash(domain, types, order);
	// sign and compact
	const signature = userWallet.signingKey.sign(eip712Hash).compactSerialized; // ERC-2098 representation

	return { order, signature };
};

// swap 1 USDC on Mainnet to WETH on Optimism
const order = await buildAndSignOrder(
	USDC_ADDRESS_ETH,
	6,
	WETH_ADDRESS_OP,
	18,
	srcChainId,
	destChainId,
	10 ** 18,
);


```

## Partner Fees

{% hint style="info" %}
This is just technical explanation. If you are using our [Order Building](#build-a-delta-order-to-sign) endpoint, this knowledge is not required.
{% endhint %}

The fees are enabled by encoding `partnerAndFee` param of the order, before its signed by a user.

The param includes three values:

* `partnerAddress` - on-chain address which will be able to collect the fees.
* `partnerFeeBps` - flat fee percent which will be taken from the order. The value is in **base points** (`100`is `1%`), which the maximum allowed value of `200`.
* `partnerTakeSurplus` - a flag that, if set, allows the partner to collect `50%` of the `surplus` as fees. It has no impact if passed together with `partnerFeeBps`, since `partnerFeeBps` takes precedence.

These are encoded into a single `uint256` value, which then is used as `partnerAndFee`.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.velora.xyz/api/velora-api/velora-delta-api/build-a-delta-order-to-sign.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.