Trades API: Manage the Cross-Chain Trade Lifecycle

These are the v1 (pre-BLS) docs, kept for reference — this page describes the retired flow. The current design is under v2 in the version picker.

A trade represents a single cross-chain transfer initiated by a Bridger against a Maker’s liquidity ad. The trade lifecycle spans two chains: the Bridger deposits tokens on the order chain via the OrderPortal contract, and the Maker locks tokens on the ad chain via the AdManager contract. Settlement is coordinated by zero-knowledge proofs that unlock funds for both parties simultaneously. Several trade endpoints return signed contract call data that your application must submit on-chain. After each on-chain transaction is confirmed, call the corresponding /confirm endpoint to advance the trade state in the relayer.

All amounts are decimal strings representing values in the smallest token unit (e.g., "1000000" for 1 USDC with 6 decimals).

GET /v1/trades/all

List trades with optional filters. Returns a paginated list.

Query parameters

string

Filter by route UUID.

string

Filter by the advertisement UUID.

string

Filter by the Maker’s blockchain address.

string

Filter by the Bridger’s blockchain address.

string

Filter by the UUID of the source token.

string

Filter by the UUID of the destination token.

string

Return only trades with an amount greater than or equal to this value.

string

Return only trades with an amount less than or equal to this value.

string

Pagination cursor from a previous response’s nextCursor field.

number

default:"25"

Number of results per page. Between 1 and 100.

Response fields

Trade[]

required

Array of trade objects. See the Trade object fields section.

string | null

required

Cursor for the next page. null on the last page.

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "routeId": "123e4567-e89b-12d3-a456-426614174000",
      "adId": "b693ab22-5e73-47e8-9937-1d4459b8c081",
      "adCreatorAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
      "adChainId": "296",
      "orderChainId": "11155111",
      "bridgerAddress": "0x1A2B3C4D5E6F7A8B9C0D1E2F3A4B5C6D7E8F9A0B",
      "amount": "500000000",
      "status": "PENDING",
      "adCreatorClaimed": false,
      "bridgerClaimed": false,
      "createdAt": "2026-04-15T10:00:00.000Z",
      "updatedAt": "2026-04-15T10:00:00.000Z",
      "ad": {
        "id": "b693ab22-5e73-47e8-9937-1d4459b8c081",
        "routeId": "123e4567-e89b-12d3-a456-426614174000",
        "creatorAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
      },
      "route": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "adToken": {
          "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
          "symbol": "wETH",
          "kind": "SEP41",
          "address": "CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
          "decimals": 18,
          "chain": { "name": "Stellar Testnet", "chainId": "1000001", "kind": "STELLAR" }
        },
        "orderToken": {
          "id": "d290f1ee-6c54-4b01-90e6-d701748f0852",
          "symbol": "ETH",
          "kind": "NATIVE",
          "address": "0x0000000000000000000000000000000000000000",
          "decimals": 18,
          "chain": { "name": "Ethereum Sepolia", "chainId": "11155111", "kind": "EVM" }
        }
      }
    }
  ],
  "nextCursor": null
}

GET /v1/trades/:id

Retrieve a single trade by its UUID.

Path parameters

string

required

UUID of the trade to retrieve.

Returns a single Trade object.

POST /v1/trades/create

Create a new trade as a Bridger against an existing ad. The response contains signed transaction data that you must submit to the OrderPortal contract on the order chain to make the deposit. After the deposit is confirmed, call POST /v1/trades/:id/confirm. Requires authentication.

Request body

string

required

UUID of the ad to trade against.

string

required

UUID of the route for this trade. Must match the route associated with the ad.

string

required

Amount of tokens to deposit, in the smallest token unit. Must fall within the ad’s minAmount and maxAmount constraints.

string

required

The Bridger’s destination address on the ad chain, where the Maker’s tokens will be released.

Response fields

string

required

UUID of the newly created trade.

object

required

Show Contract call details

string

required

Chain ID of the OrderPortal contract.

string

required

Address of the OrderPortal contract to call.

string

required

Relayer signature authorizing this order.

string

required

Authorization token to pass to the contract.

number

required

Seconds until this signed request expires.

object

required

Structured order parameters for the OrderPortal contract. Contains token addresses, amounts, chain IDs, bridger/creator addresses, and a cryptographic salt.

string

required

Hash of the order parameters, used for on-chain verification.

string

required

Hash of the relayer-signed request.

string

required

"EVM" or "STELLAR".

{
  "adId": "b693ab22-5e73-47e8-9937-1d4459b8c081",
  "routeId": "123e4567-e89b-12d3-a456-426614174000",
  "amount": "500000000",
  "bridgerDstAddress": "0x1A2B3C4D5E6F7A8B9C0D1E2F3A4B5C6D7E8F9A0B"
}

{
  "tradeId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "reqContractDetails": {
    "chainId": "11155111",
    "contractAddress": "0xB2C3D4E5F60718293A4B5C6D7E8F9012345678AB",
    "signature": "0x8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b01",
    "authToken": "0xf0a1b2c3d4e5f607081920212223242526272829",
    "timeToExpire": 3600,
    "orderParams": {
      "orderChainToken": "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238",
      "adChainToken": "0xA0b86a33E6441cD3b27CA2E60b05C5FBA3B6dE9B",
      "amount": "500000000",
      "bridger": "0x1A2B3C4D5E6F7A8B9C0D1E2F3A4B5C6D7E8F9A0B",
      "orderRecipient": "0x1A2B3C4D5E6F7A8B9C0D1E2F3A4B5C6D7E8F9A0B",
      "adChainId": "296",
      "adManager": "0xA1B2C3D4E5F60718293A4B5C6D7E8F9012345678",
      "adId": "b693ab22-5e73-47e8-9937-1d4459b8c081",
      "adCreator": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
      "adRecipient": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
      "salt": "7392841056"
    },
    "orderHash": "0x4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f",
    "reqHash": "0x6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b",
    "chainKind": "EVM"
  }
}

GET /v1/trades/:id/params

Retrieve the order parameters for a trade. Use this to reconstruct the exact parameters needed to call the OrderPortal or AdManager contract independently. Requires authentication.

Path parameters

string

required

UUID of the trade.

Response fields

string

required

Token contract address on the order chain.

string

required

Token contract address on the ad chain.

string

required

Trade amount in the smallest token unit.

string

required

Bridger’s address.

string

required

Address that receives tokens on the order chain.

string

required

The associated ad identifier.

string

required

Maker’s address.

string

required

Address that receives tokens on the ad chain.

string

required

Cryptographic salt for this order, used to prevent replay attacks.

string

Chain ID of the order chain.

string

Address of the OrderPortal contract on the order chain.

string

Chain ID of the ad chain.

string

Address of the AdManager contract on the ad chain.

{
  "orderChainToken": "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238",
  "adChainToken": "0xA0b86a33E6441cD3b27CA2E60b05C5FBA3B6dE9B",
  "amount": "500000000",
  "bridger": "0x1A2B3C4D5E6F7A8B9C0D1E2F3A4B5C6D7E8F9A0B",
  "orderRecipient": "0x1A2B3C4D5E6F7A8B9C0D1E2F3A4B5C6D7E8F9A0B",
  "adId": "b693ab22-5e73-47e8-9937-1d4459b8c081",
  "adCreator": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
  "adRecipient": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
  "salt": "7392841056",
  "orderChainId": "11155111",
  "orderPortal": "0xB2C3D4E5F60718293A4B5C6D7E8F9012345678AB",
  "adChainId": "296",
  "adManager": "0xA1B2C3D4E5F60718293A4B5C6D7E8F9012345678"
}

POST /v1/trades/:id/lock

Lock funds on the ad chain in response to a Bridger’s deposit. This is a Maker action — only the Maker whose ad is associated with this trade can call this endpoint. Returns signed transaction data to submit to the AdManager contract. Requires authentication.

Path parameters

string

required

UUID of the trade to lock.

Response fields

string

required

Chain ID of the AdManager contract.

string

required

Address of the AdManager contract.

string

required

Relayer signature authorizing the lock.

string

required

Authorization token to pass to the contract.

number

required

Seconds until this signed request expires.

object

required

Full AdManager order parameters for the lock transaction.

string

required

Hash of the relayer-signed request.

string

required

Hash of the order parameters.

string

required

"EVM" or "STELLAR".

{
  "chainId": "296",
  "contractAddress": "0xA1B2C3D4E5F60718293A4B5C6D7E8F9012345678",
  "signature": "0x2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c01",
  "authToken": "0xb8c9d0e1f2a3b4c5d6e7f8091011121314151617",
  "timeToExpire": 3600,
  "orderParams": {
    "orderChainToken": "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238",
    "adChainToken": "0xA0b86a33E6441cD3b27CA2E60b05C5FBA3B6dE9B",
    "amount": "500000000",
    "bridger": "0x1A2B3C4D5E6F7A8B9C0D1E2F3A4B5C6D7E8F9A0B",
    "orderChainId": "11155111",
    "srcOrderPortal": "0xB2C3D4E5F60718293A4B5C6D7E8F9012345678AB",
    "orderRecipient": "0x1A2B3C4D5E6F7A8B9C0D1E2F3A4B5C6D7E8F9A0B",
    "adId": "b693ab22-5e73-47e8-9937-1d4459b8c081",
    "adCreator": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "adRecipient": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "salt": "7392841056"
  },
  "reqHash": "0x8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d",
  "orderHash": "0x0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f",
  "chainKind": "EVM"
}

POST /v1/trades/:id/unlock

Request unlock data to claim your locked funds after the trade is settled. Both the Bridger and the Maker call this endpoint on their respective chains. The response contains a zero-knowledge proof (proof), a nullifier hash, and signed contract data for either the OrderPortal (Bridger) or AdManager (Maker). Requires authentication.

Path parameters

string

required

UUID of the trade to unlock.

Request body

string

required

Your wallet signature authorizing the unlock request. This prevents unauthorized parties from requesting unlock data on your behalf.

Response fields

string

required

Chain ID of the contract to call.

string

required

Contract address to call for the unlock.

string

required

Relayer signature for the unlock transaction.

string

required

Authorization token to pass to the contract.

number

required

Seconds until this signed request expires.

object

required

Order parameters for the unlock call.

string

required

Cryptographic nullifier preventing double-spend of this settlement.

string

required

Merkle root used for deposit inclusion verification.

string

required

Serialized zero-knowledge proof attesting that the deposit is included in the on-chain Merkle tree.

string

required

Hash of the order parameters.

string

required

Hash of the relayer-signed request.

string

required

"EVM" or "STELLAR".

{
  "signature": "0x3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d01"
}

{
  "chainId": "11155111",
  "contractAddress": "0xB2C3D4E5F60718293A4B5C6D7E8F9012345678AB",
  "signature": "0x9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b01",
  "authToken": "0xc9d0e1f2a3b4c5d6e7f8091011121314151617181920",
  "timeToExpire": 3600,
  "orderParams": {
    "orderChainToken": "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238",
    "adChainToken": "0xA0b86a33E6441cD3b27CA2E60b05C5FBA3B6dE9B",
    "amount": "500000000",
    "bridger": "0x1A2B3C4D5E6F7A8B9C0D1E2F3A4B5C6D7E8F9A0B",
    "orderRecipient": "0x1A2B3C4D5E6F7A8B9C0D1E2F3A4B5C6D7E8F9A0B",
    "adChainId": "296",
    "adManager": "0xA1B2C3D4E5F60718293A4B5C6D7E8F9012345678",
    "adId": "b693ab22-5e73-47e8-9937-1d4459b8c081",
    "adCreator": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "adRecipient": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "salt": "7392841056"
  },
  "nullifierHash": "0xf1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2",
  "targetRoot": "0xa3b4c5d6e7f8091011121314151617181920212223242526272829303132333435",
  "proof": "0x1234567890abcdef...truncated",
  "orderHash": "0x4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f",
  "reqHash": "0x6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b",
  "chainKind": "EVM"
}

POST /v1/trades/:id/unlock/confirm

Confirm that an unlock transaction has been submitted on-chain. Call this after successfully submitting the transaction data returned by /unlock. Requires authentication.

Path parameters

string

required

UUID of the trade.

Request body

string

required

Transaction hash of the on-chain unlock transaction.

string

Optional signature for the confirmation.

Response fields

string

required

UUID of the trade.

boolean

required

true when the relayer successfully recorded the confirmation.

{
  "txHash": "0x7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c"
}

{
  "tradeId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "success": true
}

POST /v1/trades/:id/confirm

Confirm a general on-chain action for a trade (e.g., after the initial deposit transaction). Call this after any trade-related on-chain transaction that is not an unlock. Requires authentication.

Path parameters

string

required

UUID of the trade.

Request body

string

required

Transaction hash of the confirmed on-chain transaction.

string

Optional signature for the confirmation.

Response fields

string

required

UUID of the trade.

boolean

required

true when the relayer successfully recorded the confirmation.

{
  "txHash": "0x9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e"
}

{
  "tradeId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "success": true
}

Trade object fields

string

required

UUID of the trade.

string

required

UUID of the route this trade follows.

string

required

UUID of the ad this trade is placed against.

string

required

Blockchain address of the Maker.

string

required

Chain ID of the ad (source) chain.

string

required

Chain ID of the order (destination) chain.

string

required

Blockchain address of the Bridger.

string

required

Trade amount in the smallest token unit.

string

required

Current trade status (e.g., "PENDING", "LOCKED", "SETTLED").

boolean

required

Whether the Maker has claimed their funds.

boolean

required

Whether the Bridger has claimed their funds.

string

required

ISO 8601 timestamp of trade creation.

string

required

ISO 8601 timestamp of the last status update.

object

required

Summary of the associated ad: id, routeId, creatorAddress.

object

required

Route details including adToken and orderToken with their chain information.

Overview

Endpoints

Trades API: Manage the Cross-Chain Trade Lifecycle

GET /v1/trades/all

Query parameters

Response fields

GET /v1/trades/:id

Path parameters

POST /v1/trades/create

Request body

Response fields

GET /v1/trades/:id/params

Path parameters

Response fields

POST /v1/trades/:id/lock

Path parameters

Response fields

POST /v1/trades/:id/unlock

Path parameters

Request body

Response fields

POST /v1/trades/:id/unlock/confirm

Path parameters

Request body

Response fields

POST /v1/trades/:id/confirm

Path parameters

Request body

Response fields

Trade object fields

​GET /v1/trades/all

​Query parameters

​Response fields

​GET /v1/trades/:id

​Path parameters

​POST /v1/trades/create

​Request body

​Response fields

​GET /v1/trades/:id/params

​Path parameters

​Response fields

​POST /v1/trades/:id/lock

​Path parameters

​Response fields

​POST /v1/trades/:id/unlock

​Path parameters

​Request body

​Response fields

​POST /v1/trades/:id/unlock/confirm

​Path parameters

​Request body

​Response fields

​POST /v1/trades/:id/confirm

​Path parameters

​Request body

​Response fields

​Trade object fields

GET /v1/trades/all

Query parameters

Response fields

GET /v1/trades/:id

Path parameters

POST /v1/trades/create

Request body

Response fields

GET /v1/trades/:id/params

Path parameters

Response fields

POST /v1/trades/:id/lock

Path parameters

Response fields

POST /v1/trades/:id/unlock

Path parameters

Request body

Response fields

POST /v1/trades/:id/unlock/confirm

Path parameters

Request body

Response fields

POST /v1/trades/:id/confirm

Path parameters

Request body

Response fields

Trade object fields