Trades API: Manage the Cross-Chain Trade Lifecycle

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

routeId

string

Filter by route UUID.

adId

string

Filter by the advertisement UUID.

adCreatorAddress

string

Filter by the Maker’s blockchain address.

bridgerAddress

string

Filter by the Bridger’s blockchain address.

adTokenId

string

Filter by the UUID of the source token.

orderTokenId

string

Filter by the UUID of the destination token.

minAmount

string

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

maxAmount

string

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

cursor

string

Pagination cursor from a previous response’s nextCursor field.

limit

number

default:"25"

Number of results per page. Between 1 and 100.

Response fields

data

Trade[]

required

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

nextCursor

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

adId

string

required

UUID of the ad to trade against.

routeId

string

required

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

amount

string

required

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

bridgerDstAddress

string

required

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

Response fields

tradeId

string

required

UUID of the newly created trade.

reqContractDetails

object

required

Show Contract call details

chainId

string

required

Chain ID of the OrderPortal contract.

contractAddress

string

required

Address of the OrderPortal contract to call.

signature

string

required

Relayer signature authorizing this order.

authToken

string

required

Authorization token to pass to the contract.

timeToExpire

number

required

Seconds until this signed request expires.

orderParams

object

required

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

orderHash

string

required

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

reqHash

string

required

Hash of the relayer-signed request.

chainKind

string

required

"EVM" or "STELLAR".

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

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

orderChainToken

string

required

Token contract address on the order chain.

adChainToken

string

required

Token contract address on the ad chain.

amount

string

required

Trade amount in the smallest token unit.

bridger

string

required

Bridger’s address.

orderRecipient

string

required

Address that receives tokens on the order chain.

adId

string

required

The associated ad identifier.

adCreator

string

required

Maker’s address.

adRecipient

string

required

Address that receives tokens on the ad chain.

salt

string

required

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

orderChainId

string

Chain ID of the order chain.

orderPortal

string

Address of the OrderPortal contract on the order chain.

adChainId

string

Chain ID of the ad chain.

adManager

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

chainId

string

required

Chain ID of the AdManager contract.

contractAddress

string

required

Address of the AdManager contract.

signature

string

required

Relayer signature authorizing the lock.

authToken

string

required

Authorization token to pass to the contract.

timeToExpire

number

required

Seconds until this signed request expires.

orderParams

object

required

Full AdManager order parameters for the lock transaction.

reqHash

string

required

Hash of the relayer-signed request.

orderHash

string

required

Hash of the order parameters.

chainKind

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

signature

string

required

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

Response fields

chainId

string

required

Chain ID of the contract to call.

contractAddress

string

required

Contract address to call for the unlock.

signature

string

required

Relayer signature for the unlock transaction.

authToken

string

required

Authorization token to pass to the contract.

timeToExpire

number

required

Seconds until this signed request expires.

orderParams

object

required

Order parameters for the unlock call.

nullifierHash

string

required

Cryptographic nullifier preventing double-spend of this settlement.

targetRoot

string

required

Merkle root used for deposit inclusion verification.

proof

string

required

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

orderHash

string

required

Hash of the order parameters.

reqHash

string

required

Hash of the relayer-signed request.

chainKind

string

required

"EVM" or "STELLAR".

{
  "signature": "0x3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d01"
}

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

txHash

string

required

Transaction hash of the on-chain unlock transaction.

signature

string

Optional signature for the confirmation.

Response fields

tradeId

string

required

UUID of the trade.

success

boolean

required

true when the relayer successfully recorded the confirmation.

{
  "txHash": "0x7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c"
}

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

txHash

string

required

Transaction hash of the confirmed on-chain transaction.

signature

string

Optional signature for the confirmation.

Response fields

tradeId

string

required

UUID of the trade.

success

boolean

required

true when the relayer successfully recorded the confirmation.

{
  "txHash": "0x9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e"
}

Trade object fields

string

required

UUID of the trade.

routeId

string

required

UUID of the route this trade follows.

adId

string

required

UUID of the ad this trade is placed against.

adCreatorAddress

string

required

Blockchain address of the Maker.

adChainId

string

required

Chain ID of the ad (source) chain.

orderChainId

string

required

Chain ID of the order (destination) chain.

bridgerAddress

string

required

Blockchain address of the Bridger.

amount

string

required

Trade amount in the smallest token unit.

status

string

required

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

adCreatorClaimed

boolean

required

Whether the Maker has claimed their funds.

bridgerClaimed

boolean

required

Whether the Bridger has claimed their funds.

createdAt

string

required

ISO 8601 timestamp of trade creation.

updatedAt

string

required

ISO 8601 timestamp of the last status update.

object

required

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

route

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

Overview

Endpoints

​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