Ads API: Create and Manage Liquidity Advertisements

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.

Liquidity advertisements (ads) are the core primitive of the ProofBridge marketplace. A Maker creates an ad to signal that they are willing to provide liquidity on a specific cross-chain route — for example, locking wETH on Stellar so bridgers can receive ETH on Ethereum. The ad lifecycle moves through several states (ACTIVE, PAUSED, EXHAUSTED, CLOSED) as the Maker manages their liquidity. Most ad endpoints return blockchain transaction data (contract address, signature, auth token) that your application must submit to the smart contract to finalize the operation on-chain. After the on-chain transaction is confirmed, call the corresponding /confirm endpoint to notify the relayer.

All amounts are expressed in the smallest unit of the token (e.g., wei for EVM tokens, stroops for Stellar). Always pass amounts as decimal strings, not numbers, to avoid integer overflow.

GET /v1/ads

List ads with optional filters. Returns a paginated list.

Query parameters

string

Filter by route UUID. Only ads that belong to this route are returned.

string

Filter by the ad creator’s blockchain address.

number

Filter by the chain ID of the source (ad) token.

number

Filter by the chain ID of the destination (order) token.

string

Filter by the UUID of the source token.

string

Filter by the UUID of the destination token.

string

Filter by ad status. One of "ACTIVE", "PAUSED", "EXHAUSTED", or "CLOSED".

string

Pagination cursor from a previous response’s nextCursor field.

number

default:"25"

Number of results to return per page.

Response fields

Ad[]

required

Array of ad objects. See the Ad object fields section below.

string | null

required

Cursor for the next page. null when you have reached the last page.

{
  "data": [
    {
      "id": "b693ab22-5e73-47e8-9937-1d4459b8c081",
      "creatorAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
      "routeId": "123e4567-e89b-12d3-a456-426614174000",
      "adTokenId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "orderTokenId": "d290f1ee-6c54-4b01-90e6-d701748f0852",
      "poolAmount": "5000000000",
      "availableAmount": "3200000000",
      "minAmount": "100000000",
      "maxAmount": "1000000000",
      "status": "ACTIVE",
      "metadata": null,
      "adToken": {
        "name": "USD Coin",
        "symbol": "USDC",
        "address": "0xA0b86a33E6441cD3b27CA2E60b05C5FBA3B6dE9B",
        "decimals": 6,
        "chainId": "296",
        "chainKind": "EVM",
        "kind": "ERC20"
      },
      "orderToken": {
        "name": "USD Coin",
        "symbol": "USDC",
        "address": "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238",
        "decimals": 6,
        "chainId": "11155111",
        "chainKind": "EVM",
        "kind": "ERC20"
      },
      "createdAt": "2026-04-10T09:00:00.000Z",
      "updatedAt": "2026-04-14T15:30:00.000Z"
    }
  ],
  "nextCursor": null
}

GET /v1/ads/:id

Retrieve a single ad by its UUID.

Path parameters

string

required

UUID of the ad to retrieve.

Response fields

Returns a single Ad object.

{
  "id": "b693ab22-5e73-47e8-9937-1d4459b8c081",
  "creatorAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
  "routeId": "123e4567-e89b-12d3-a456-426614174000",
  "adTokenId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "orderTokenId": "d290f1ee-6c54-4b01-90e6-d701748f0852",
  "poolAmount": "5000000000",
  "availableAmount": "3200000000",
  "minAmount": "100000000",
  "maxAmount": "1000000000",
  "status": "ACTIVE",
  "metadata": null,
  "adToken": {
    "name": "USD Coin",
    "symbol": "USDC",
    "address": "0xA0b86a33E6441cD3b27CA2E60b05C5FBA3B6dE9B",
    "decimals": 6,
    "chainId": "296",
    "chainKind": "EVM",
    "kind": "ERC20"
  },
  "orderToken": {
    "name": "USD Coin",
    "symbol": "USDC",
    "address": "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238",
    "decimals": 6,
    "chainId": "11155111",
    "chainKind": "EVM",
    "kind": "ERC20"
  },
  "createdAt": "2026-04-10T09:00:00.000Z",
  "updatedAt": "2026-04-14T15:30:00.000Z"
}

POST /v1/ads/create

Create a new liquidity ad. The response contains signed transaction data that you must submit to the AdManager smart contract on-chain to activate the ad. After the transaction is mined, call POST /v1/ads/:id/confirm with the transaction hash. Requires authentication.

Request body

string

required

UUID of the route this ad will serve. Determines the source and destination token pair.

string

required

The destination blockchain address where the Maker will receive bridged funds.

string

required

Initial amount to deposit into the ad pool, in the smallest token unit (e.g., "1000000000" for 1000 USDC with 6 decimals).

string

Minimum trade amount the ad will accept, in the smallest token unit. Optional.

string

Maximum trade amount the ad will accept, in the smallest token unit. Optional.

object

Arbitrary JSON metadata to associate with the ad (e.g., display name, fee rate).

Response fields

string

required

Chain ID where the AdManager contract is deployed.

string

required

Address of the AdManager contract to call.

string

required

Relayer signature authorizing the transaction.

string

Relayer signer public key. Returned for Stellar chains only.

string

required

Request authorization token to pass to the contract.

number

required

Seconds until the signed request expires and must be re-requested.

string

required

The relayer-assigned identifier for this ad.

string

required

Token contract address for the ad (source) token.

string

required

Initial funding amount confirmed by the relayer.

string

required

Chain ID of the destination (order) chain.

string

required

Recipient address for the ad on the source chain.

string

required

Hash of the relayer-signed request, used for on-chain verification.

string

required

Chain family of the ad contract: "EVM" or "STELLAR".

{
  "routeId": "123e4567-e89b-12d3-a456-426614174000",
  "creatorDstAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
  "fundAmount": "1000000000",
  "minAmount": "10000000",
  "maxAmount": "500000000",
  "metadata": { "label": "My USDC liquidity ad" }
}

{
  "chainId": "296",
  "contractAddress": "0xA1B2C3D4E5F60718293A4B5C6D7E8F9012345678",
  "signature": "0x4d2a1c3e5f6b7a8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c01",
  "authToken": "0xd3a4f5b6c7e8091a2b3c4d5e6f7089abcdef1234",
  "timeToExpire": 3600,
  "adId": "b693ab22-5e73-47e8-9937-1d4459b8c081",
  "adToken": "0xA0b86a33E6441cD3b27CA2E60b05C5FBA3B6dE9B",
  "initialAmount": "1000000000",
  "orderChainId": "11155111",
  "adRecipient": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
  "reqHash": "0x7b8c9d0e1f2a3b4c5d6e7f8091a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f901",
  "chainKind": "EVM"
}

POST /v1/ads/:id/fund

Add more tokens to an existing ad’s liquidity pool. Returns signed transaction data to submit to the AdManager contract. After the transaction is confirmed, call POST /v1/ads/:id/confirm. Requires authentication.

Path parameters

string

required

UUID of the ad to fund.

Request body

string

required

Amount to add to the pool, in the smallest token unit.

Response fields

string

required

Chain ID of the AdManager contract.

string

required

Address of the AdManager contract to call.

string

required

Relayer signature for this funding request.

string

required

Request authorization token to pass to the contract.

number

required

Seconds until this signed request expires.

string

required

The ad identifier.

string

required

Funding amount confirmed by the relayer.

string

required

Hash of the relayer-signed request.

string

required

"EVM" or "STELLAR".

{
  "poolAmountTopUp": "500000000"
}

{
  "chainId": "296",
  "contractAddress": "0xA1B2C3D4E5F60718293A4B5C6D7E8F9012345678",
  "signature": "0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b01",
  "authToken": "0xc7d8e9f0a1b2c3d4e5f607081920abcdef567890",
  "timeToExpire": 3600,
  "adId": "b693ab22-5e73-47e8-9937-1d4459b8c081",
  "amount": "500000000",
  "reqHash": "0x3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c45",
  "chainKind": "EVM"
}

POST /v1/ads/:id/withdraw

Initiate a partial withdrawal from an ad’s pool. Returns signed transaction data to submit to the AdManager contract. After the transaction is confirmed, call POST /v1/ads/:id/confirm. Requires authentication.

Path parameters

string

required

UUID of the ad to withdraw from.

Request body

string

required

Amount to withdraw from the pool, in the smallest token unit.

string

required

Destination address to receive the withdrawn funds.

Response fields

string

required

Chain ID of the AdManager contract.

string

required

Address of the AdManager contract to call.

string

required

Relayer signature for this withdrawal request.

string

required

Request authorization token.

number

required

Seconds until this signed request expires.

string

required

The ad identifier.

string

required

Withdrawal amount confirmed by the relayer.

string

required

Destination address for the withdrawn funds.

string

required

Hash of the relayer-signed request.

string

required

"EVM" or "STELLAR".

{
  "poolAmountWithdraw": "200000000",
  "to": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
}

{
  "chainId": "296",
  "contractAddress": "0xA1B2C3D4E5F60718293A4B5C6D7E8F9012345678",
  "signature": "0x9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a01",
  "authToken": "0xe5f6a7b8c9d0e1f2a3b4c5d6e7f8091011121314",
  "timeToExpire": 3600,
  "adId": "b693ab22-5e73-47e8-9937-1d4459b8c081",
  "amount": "200000000",
  "to": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
  "reqHash": "0x5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e",
  "chainKind": "EVM"
}

POST /v1/ads/:id/confirm

Notify the relayer that a previously-initiated blockchain transaction (create, fund, or withdraw) has been confirmed on-chain. This updates the ad’s state in the relayer database. Requires authentication.

Path parameters

string

required

UUID of the ad.

Request body

string

required

Transaction hash of the confirmed on-chain transaction.

string

Optional additional signature for the confirmation.

Response fields

string

required

UUID of the confirmed ad.

boolean

required

true when the relayer successfully recorded the confirmation.

{
  "txHash": "0x123f681646d4a755815f9cb19e1acc8565a0c2ac8e625e37ef3dbf9c8feb8a7e"
}

{
  "adId": "b693ab22-5e73-47e8-9937-1d4459b8c081",
  "success": true
}

PATCH /v1/ads/:id/update

Update mutable parameters on an existing ad. You can change the ad’s status, min/max trade amounts, or metadata without an on-chain transaction. Requires authentication.

Path parameters

string

required

UUID of the ad to update.

Request body

string

New status for the ad. Must be "ACTIVE" or "PAUSED".

string

New minimum trade amount in the smallest token unit.

string

New maximum trade amount in the smallest token unit.

object

Updated metadata to replace the existing ad metadata.

Response fields

string

required

UUID of the updated ad.

string

required

Address of the ad creator.

string | null

required

Updated minimum amount, or null if unset.

string | null

required

Updated maximum amount, or null if unset.

any

required

Updated metadata.

{
  "status": "PAUSED",
  "minAmount": "50000000",
  "maxAmount": "750000000"
}

{
  "id": "b693ab22-5e73-47e8-9937-1d4459b8c081",
  "creatorAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
  "minAmount": "50000000",
  "maxAmount": "750000000",
  "metadata": null
}

POST /v1/ads/:id/close

Permanently close an ad and withdraw all remaining funds. Returns signed transaction data to submit to the AdManager contract. This action is irreversible. Requires authentication.

Closing an ad is permanent. Any active trades against this ad must be settled before closing.

Path parameters

string

required

UUID of the ad to close.

Request body

string

required

Address to receive the remaining pool balance when the ad is closed.

Response fields

string

required

Chain ID of the AdManager contract.

string

required

Address of the AdManager contract to call.

string

required

Relayer signature for this close request.

string

required

Request authorization token.

number

required

Seconds until this signed request expires.

string

required

The ad identifier.

string

required

Destination address for the remaining funds.

string

required

Hash of the relayer-signed request.

string

required

"EVM" or "STELLAR".

{
  "to": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
}

{
  "chainId": "296",
  "contractAddress": "0xA1B2C3D4E5F60718293A4B5C6D7E8F9012345678",
  "signature": "0xd4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f601",
  "authToken": "0xa1b2c3d4e5f6070819202122232425262728293031",
  "timeToExpire": 3600,
  "adId": "b693ab22-5e73-47e8-9937-1d4459b8c081",
  "to": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
  "reqHash": "0xe7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8",
  "chainKind": "EVM"
}

Ad object fields

The following fields appear on every ad object returned by GET /v1/ads and GET /v1/ads/:id.

string

required

UUID of the ad.

string

required

Blockchain address of the Maker who created the ad.

string

required

UUID of the cross-chain route this ad serves.

string

required

UUID of the source (ad) token.

string

required

UUID of the destination (order) token.

string

required

Total amount ever deposited into this ad’s pool, in the smallest token unit.

string

required

Current available (unlocked) balance in the pool, in the smallest token unit.

string | null

required

Minimum trade amount the ad accepts, or null if no minimum is set.

string | null

required

Maximum trade amount the ad accepts, or null if no maximum is set.

string

required

Current ad status: "ACTIVE", "PAUSED", "EXHAUSTED", or "CLOSED".

any

Arbitrary metadata set by the Maker. Can be null.

object

required

Show Token fields

string

Token name (e.g., "USD Coin").

string

Token symbol (e.g., "USDC").

string

Token contract address.

number

Number of decimal places.

string

Chain ID where this token lives.

string

"EVM" or "STELLAR".

string

Token standard: "ERC20", "NATIVE", "SAC", or "SEP41".

object

required

Same structure as adToken, for the destination token.

string

required

ISO 8601 timestamp of when the ad was created.

string

required

ISO 8601 timestamp of the last update to the ad.

Overview

Endpoints

Ads API: Create and Manage Liquidity Advertisements

GET /v1/ads

Query parameters

Response fields

GET /v1/ads/:id

Path parameters

Response fields

POST /v1/ads/create

Request body

Response fields

POST /v1/ads/:id/fund

Path parameters

Request body

Response fields

POST /v1/ads/:id/withdraw

Path parameters

Request body

Response fields

POST /v1/ads/:id/confirm

Path parameters

Request body

Response fields

PATCH /v1/ads/:id/update

Path parameters

Request body

Response fields

POST /v1/ads/:id/close

Path parameters

Request body

Response fields

Ad object fields

​GET /v1/ads

​Query parameters

​Response fields

​GET /v1/ads/:id

​Path parameters

​Response fields

​POST /v1/ads/create

​Request body

​Response fields

​POST /v1/ads/:id/fund

​Path parameters

​Request body

​Response fields

​POST /v1/ads/:id/withdraw

​Path parameters

​Request body

​Response fields

​POST /v1/ads/:id/confirm

​Path parameters

​Request body

​Response fields

​PATCH /v1/ads/:id/update

​Path parameters

​Request body

​Response fields

​POST /v1/ads/:id/close

​Path parameters

​Request body

​Response fields

​Ad object fields

GET /v1/ads

Query parameters

Response fields

GET /v1/ads/:id

Path parameters

Response fields

POST /v1/ads/create

Request body

Response fields

POST /v1/ads/:id/fund

Path parameters

Request body

Response fields

POST /v1/ads/:id/withdraw

Path parameters

Request body

Response fields

POST /v1/ads/:id/confirm

Path parameters

Request body

Response fields

PATCH /v1/ads/:id/update

Path parameters

Request body

Response fields

POST /v1/ads/:id/close

Path parameters

Request body

Response fields

Ad object fields