Ads API: Create and Manage Liquidity Advertisements

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

routeId

string

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

creatorAddress

string

Filter by the ad creator’s blockchain address.

adChainId

number

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

orderChainId

number

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

adTokenId

string

Filter by the UUID of the source token.

orderTokenId

string

Filter by the UUID of the destination token.

status

string

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

cursor

string

Pagination cursor from a previous response’s nextCursor field.

limit

number

default:"25"

Number of results to return per page.

Response fields

data

Ad[]

required

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

nextCursor

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

routeId

string

required

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

creatorDstAddress

string

required

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

fundAmount

string

required

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

minAmount

string

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

maxAmount

string

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

metadata

object

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

Response fields

chainId

string

required

Chain ID where the AdManager contract is deployed.

contractAddress

string

required

Address of the AdManager contract to call.

signature

string

required

Relayer signature authorizing the transaction.

signerPublicKey

string

Relayer signer public key. Returned for Stellar chains only.

authToken

string

required

Request authorization token to pass to the contract.

timeToExpire

number

required

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

adId

string

required

The relayer-assigned identifier for this ad.

adToken

string

required

Token contract address for the ad (source) token.

initialAmount

string

required

Initial funding amount confirmed by the relayer.

orderChainId

string

required

Chain ID of the destination (order) chain.

adRecipient

string

required

Recipient address for the ad on the source chain.

reqHash

string

required

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

chainKind

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" }
}

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

poolAmountTopUp

string

required

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

Response fields

chainId

string

required

Chain ID of the AdManager contract.

contractAddress

string

required

Address of the AdManager contract to call.

signature

string

required

Relayer signature for this funding request.

authToken

string

required

Request authorization token to pass to the contract.

timeToExpire

number

required

Seconds until this signed request expires.

adId

string

required

The ad identifier.

amount

string

required

Funding amount confirmed by the relayer.

reqHash

string

required

Hash of the relayer-signed request.

chainKind

string

required

"EVM" or "STELLAR".

{
  "poolAmountTopUp": "500000000"
}

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

poolAmountWithdraw

string

required

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

string

required

Destination address to receive the withdrawn funds.

Response fields

chainId

string

required

Chain ID of the AdManager contract.

contractAddress

string

required

Address of the AdManager contract to call.

signature

string

required

Relayer signature for this withdrawal request.

authToken

string

required

Request authorization token.

timeToExpire

number

required

Seconds until this signed request expires.

adId

string

required

The ad identifier.

amount

string

required

Withdrawal amount confirmed by the relayer.

string

required

Destination address for the withdrawn funds.

reqHash

string

required

Hash of the relayer-signed request.

chainKind

string

required

"EVM" or "STELLAR".

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

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

txHash

string

required

Transaction hash of the confirmed on-chain transaction.

signature

string

Optional additional signature for the confirmation.

Response fields

adId

string

required

UUID of the confirmed ad.

success

boolean

required

true when the relayer successfully recorded the confirmation.

{
  "txHash": "0x123f681646d4a755815f9cb19e1acc8565a0c2ac8e625e37ef3dbf9c8feb8a7e"
}

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

status

string

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

minAmount

string

New minimum trade amount in the smallest token unit.

maxAmount

string

New maximum trade amount in the smallest token unit.

metadata

object

Updated metadata to replace the existing ad metadata.

Response fields

string

required

UUID of the updated ad.

creatorAddress

string

required

Address of the ad creator.

minAmount

string | null

required

Updated minimum amount, or null if unset.

maxAmount

string | null

required

Updated maximum amount, or null if unset.

metadata

any

required

Updated metadata.

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

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

chainId

string

required

Chain ID of the AdManager contract.

contractAddress

string

required

Address of the AdManager contract to call.

signature

string

required

Relayer signature for this close request.

authToken

string

required

Request authorization token.

timeToExpire

number

required

Seconds until this signed request expires.

adId

string

required

The ad identifier.

string

required

Destination address for the remaining funds.

reqHash

string

required

Hash of the relayer-signed request.

chainKind

string

required

"EVM" or "STELLAR".

{
  "to": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
}

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.

creatorAddress

string

required

Blockchain address of the Maker who created the ad.

routeId

string

required

UUID of the cross-chain route this ad serves.

adTokenId

string

required

UUID of the source (ad) token.

orderTokenId

string

required

UUID of the destination (order) token.

poolAmount

string

required

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

availableAmount

string

required

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

minAmount

string | null

required

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

maxAmount

string | null

required

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

status

string

required

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

metadata

any

Arbitrary metadata set by the Maker. Can be null.

adToken

object

required

Show Token fields

name

string

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

symbol

string

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

address

string

Token contract address.

decimals

number

Number of decimal places.

chainId

string

Chain ID where this token lives.

chainKind

string

"EVM" or "STELLAR".

kind

string

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

orderToken

object

required

Same structure as adToken, for the destination token.

createdAt

string

required

ISO 8601 timestamp of when the ad was created.

updatedAt

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

Overview

Endpoints

​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