API Reference: ProofBridge Relayer REST API Overview

The ProofBridge Relayer API is the backend service that orchestrates cross-chain trading operations. You interact with it to manage liquidity advertisements, initiate and settle trades, and query supported chains and routes. Every endpoint is versioned under /v1/, and most mutating operations require a Bearer token obtained through the authentication flow.

Base URL

https://api.pfbridge.xyz

All endpoints are prefixed with /v1/. For example, to list ads you call GET https://api.pfbridge.xyz/v1/ads.

The live API base URL is served by the ProofBridge backend. If you are running a local development instance, replace the base URL with your local address (e.g., http://localhost:3000).

Authentication

Most write endpoints require an Authorization header:

Authorization: Bearer <accessToken>

You obtain accessToken by completing the SIWE (Sign-In With Ethereum) or SEP-10 (Stellar) challenge flow. See the Authentication page for the full walkthrough.

Response format

All responses are JSON. Successful responses return an HTTP 2xx status code with a JSON body. Paginated list endpoints return a data array and a nextCursor field.

{
  "data": [...],
  "nextCursor": "eyJpZCI6IjEyMyJ9"
}

Pass nextCursor back as the cursor query parameter to fetch the next page. When nextCursor is null, you have reached the last page.

Rate limiting

Standard rate limiting applies to all endpoints. If you exceed the limit, the API returns 429 Too Many Requests. Implement exponential backoff when retrying.

Utility endpoints

Method	Path	Description
`GET`	`/health`	Returns service health status.
`GET`	`/docs`	Opens the Swagger UI for interactive docs.

Endpoint groups

Authentication

Obtain and refresh access tokens using wallet-based SIWE or SEP-10 challenges.

Create and manage liquidity advertisements, fund pools, and handle the ad lifecycle.

Trades

Initiate trades, retrieve order parameters, lock and unlock funds across chains.

Routes

Query supported cross-chain token pair routes.

Chains

Retrieve supported blockchain networks and their contract addresses.

Error codes

Code	Meaning
`400`	Bad request — malformed syntax or invalid parameter combination.
`401`	Unauthorized — missing or expired `Authorization` token.
`403`	Forbidden — you do not have permission to perform this action.
`404`	Not found — the requested resource does not exist.
`422`	Validation error — request body or query params failed validation.
`500`	Internal server error — something went wrong on the server.

Error responses include a message field describing the problem:

{
  "statusCode": 422,
  "message": ["routeId must be a UUID"],
  "error": "Unprocessable Entity"
}

Overview

Endpoints

API Reference: ProofBridge Relayer REST API Overview

Base URL

Authentication

Response format

Rate limiting

Utility endpoints

Endpoint groups

Authentication

Ads

Trades

Routes

Chains

Error codes

​Base URL

​Authentication

​Response format

​Rate limiting

​Utility endpoints

​Endpoint groups

Authentication

Ads

Trades

Routes

Chains

​Error codes

Base URL

Authentication

Response format

Rate limiting

Utility endpoints

Endpoint groups

Error codes