Partner API Reference - NexBridge API

End-to-end reference for the partner integration flow: manage payout/funding addresses, create and manage orders (quote → confirm → cancel), and read your funding activity and balances.

1. Base URL

All endpoints are served from a single base URL:

https://api.nexbridge.io/v1

Endpoints are grouped under two prefixes:

Group	Prefix	Example
Addresses, Orders	`/otc`	`https://api.nexbridge.io/v1/otc/orders/quote`
Funding activity, Balances	`/funding`	`https://api.nexbridge.io/v1/funding/funding-activity`

Every path below is shown with its prefix and is relative to the base URL.

2. Authentication

Send your API key on every request:

Authorization: ApiKey otc_live_<keyId>.<secret>

A missing credential returns 401; a valid credential without access to the requested resource returns 403. Your key is scoped to your own data: list and feed endpoints are automatically filtered to you, and you cannot read another partner’s records. You never need to pass your own identifier as a filter — the API applies it for you.

3. Conventions

Money is a decimal string, never a JSON number (e.g. "1003.5"). This preserves exact precision. Send amounts as strings; expect them back as strings. amountDecimals (2 or 6) on order responses tells you the display precision for the asset.
Pagination: list endpoints take page (1-indexed, default 1) and limit (default 20, max 100). Paginated responses wrap results as { "data": [...], "pagination": { page, limit, total, totalPages } }.
Timestamps are ISO-8601 strings (UTC).
Errors are returned as: { "statusCode": number, "error": string, "message": string, "code"?: string }.

4. The partner flow at a glance

1. Register a payout address            POST /otc/addresses
       ↓ (address is reviewed and approved before it can be used)
2. Request a quote                       POST /otc/orders/quote        → QUOTED
3. Confirm the quote                     POST /otc/orders/{id}/confirm → PENDING_FUNDING
       ↓ (send your deposit to the order's funding wallet)
4. Track the deposit                     GET  /funding/funding-activity
5. Check your available balance          GET  /funding/balances
   (cancel any time while cancellable)   POST /otc/orders/{id}/cancel

Order status lifecycle: QUOTED → PENDING_FUNDING → PARTIALLY_FILLED → FILLED, with CANCELLED reachable from QUOTED, PENDING_FUNDING, and PARTIALLY_FILLED.

5. Addresses

Manage the addresses an order can pay out to / be funded from.

Method	Path	Description
`GET`	`/otc/addresses`	List your addresses (paginated, filtered)
`GET`	`/otc/addresses/{id}`	Get one address
`POST`	`/otc/addresses`	Register a new address
`PUT`	`/otc/addresses/{id}`	Update an address’s notes
`DELETE`	`/otc/addresses/{id}`	Delete an address

A newly registered address is reviewed and approved before it can be used on an order.

`GET /otc/addresses`

Query: search (substring of the address), network (address type), status, asset, page, limit. 200 → { data: Address[], pagination }.

`GET /otc/addresses/{id}`

200 → Address. 404 if not found.

`POST /otc/addresses`

{
  "type": "Liquid AMP",                              // network/address type — or use `network`
  "network": "liquid",                               // alternative to `type`
  "asset": "usdt",                                   // optional
  "address": "0x29D7d1dd5B6f9C864d9db560D72a247c178aE86B",
  "notes": "green wallet"                            // optional
}

201 → Address. 400 validation, 409 if the address already exists.

`PUT /otc/addresses/{id}`

{ "notes": "optional note" }

200 → Address.

`DELETE /otc/addresses/{id}`

204 No Content.

`Address` object

Fields include the address string, its type/network, asset, lifecycle status, screening result where applicable, and timestamps.

6. Orders

Quote, list, inspect, confirm, and cancel orders.

Method	Path	Description	Returns
`POST`	`/otc/orders/quote`	Create a quote (unconfirmed order)	`OrderDetail` (201)
`GET`	`/otc/orders`	List your orders	`Order[]` (200)
`GET`	`/otc/orders/{id}`	Get enriched order detail	`OrderDetail` (200)
`POST`	`/otc/orders/{id}/confirm`	Confirm a quoted order	`OrderSummary` (200)
`POST`	`/otc/orders/{id}/cancel`	Cancel an order	`OrderSummary` (200)

`POST /otc/orders/quote` — create a quote (unconfirmed order)

Prices the order on a fresh rate, applies your fee, and returns a QUOTED order. The quote has an expiry (quote.expiresAt).

{
  "asset_in":    "USDT",       // asset you send
  "network_in":  "ethereum",
  "asset_out":   "USTBL",      // asset you receive
  "network_out": "liquid",
  "amount":      "1000.5"      // input amount in asset_in units, decimal STRING (≤ 1e12)
}

201 → OrderDetail. Notable errors: 404 (no tradable route for this asset pair), 422 (route not tradable), 409 (conflict), 503 (price_unavailable).

`GET /otc/orders`

List your orders. Optional repeated id filter: ?id=<a>&id=<b>. 200 → array of Order (raw shape — see below; differs from the enriched OrderDetail returned by the detail endpoint).

`GET /otc/orders/{id}`

Enriched detail: summary, quote info, cancellation eligibility, and resolved wallets. 200 → OrderDetail. 404 if not found.

`POST /otc/orders/{id}/confirm` — confirm a quoted order

Confirms a QUOTED order whose quote is still valid: QUOTED → PENDING_FUNDING. 200 → OrderSummary. Errors:

409 quote_already_used — the quote was already confirmed.
409 quote_expired — the quote expired or was cancelled.

`POST /otc/orders/{id}/cancel` — cancel an order

Cancels the order when it is in a cancellable state (QUOTED, PENDING_FUNDING, or PARTIALLY_FILLED). 200 → OrderSummary. 400 if the order is not in a cancellable state.

Order response shapes

OrderSummary (returned by confirm/cancel):

{
  "id": "ae590d2b-fd40-4c49-aa2e-f91d5ede065d",
  "partner": { "id": "c3a1b2d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d" },
  "type": "subscription",                 // "subscription" | "redemption" | null
  "status": "PENDING_FUNDING",
  "quote": {
    "status": "CONSUMED",                 // ACTIVE | EXPIRED | CONSUMED | CANCELLED
    "amountIn": "1000",
    "amountOut": "1003.5",
    "expiresAt": "2026-05-20T12:00:00.000Z",
    "createdAt": "2026-05-19T10:00:00.000Z"
  },
  "canCancel": true,
  "amountDecimals": 2                      // 2 | 6 — display precision
}

OrderDetail (returned by quote/get) = OrderSummary plus:

{
  "flowType": "nb_api",
  "wallets": [
    {
      "id": "f1e2d3c4-b5a6-7890-1234-56789abcdef0",
      "label": "Funding wallet",
      "network": "ethereum",
      "platform": "fireblocks",
      "resolution": "shared",
      "address": "0xabc...5678"
    }
  ]
}

The funding wallet address in OrderDetail.wallets is where you send the deposit for a PENDING_FUNDING order.

Order (raw shape returned by GET /otc/orders list): id, userPairId, status, size, rate, amountIn, amountOut, actualFee, payoutStatus, and lifecycle timestamps (confirmationTimestamp, fulfillmentTimestamp, cancellationTimestamp, payoutStarted, payoutCompleted, expiresAt, createdAt, updatedAt). All money fields are decimal strings.

7. Funding activity & balances

After an order is confirmed and funded, track the deposit and your balance.

Method	Path	Description	Returns
`GET`	`/funding/funding-activity`	Your funding-activity feed	paginated `FundingActivityItem`
`GET`	`/funding/balances`	Your balances	paginated `BalanceRow`

`GET /funding/funding-activity` — the funding-activity feed

Paginated feed of your fundings (deposits), each annotated with the orders it is allocated to. Query: asset, network, status, order_id, date_from, date_to (all optional), plus page and limit. 200 → { data: FundingActivityItem[], pagination }:

{
  "data": [
    {
      "funding_id": "….",
      "partner_id": "….",
      "asset": "USDT",
      "network": "ethereum",
      "amount": "1000",                    // decimal string
      "status": "AVAILABLE",
      "source_wallet": { "address": "0x…", "network": "ethereum", "asset": "USDT" },
      "location_wallet": { "…": "wallet snapshot" },
      "linked_orders": [
        { "order_id": "….", "allocated_amount": "1000" }
      ],
      "created_at": "2026-05-19T10:00:00.000Z",   // deposit time
      "updated_at": "2026-05-19T12:00:00.000Z"    // latest status change
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 1, "totalPages": 1 }
}

FundingStatus values: RECEIVED, DIRTY, ELIGIBLE, TRANSFER_FAILED, AVAILABLE, PARTIALLY_ALLOCATED, ALLOCATED, CONSUMED.

linked_orders includes orders linked via live (non-cancelled) allocations; a fully consumed funding still shows what it was spent on. Amounts are summed per order across the funding’s allocations.

`GET /funding/balances` — balances

Paginated balances at (asset, network) grain — the same asset on two networks is reported as two rows, never merged. Query: asset, network (optional), plus page and limit. 200 → { data: BalanceRow[], pagination }:

{
  "data": [
    {
      "partner": "….",
      "asset": "USDT",
      "network": "ethereum",
      "available": "1000",         // spendable now
      "allocated": "0",            // reserved against open orders
      "dirty": "0",                // flagged / not yet eligible
      "total": "1000"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 1, "totalPages": 1 }
}

All balance figures are decimal strings.

8. Error reference

Status	Meaning	When
`400`	Bad request / validation	malformed payload; order not in a cancellable state
`401`	Unauthorized	missing/invalid credential
`403`	Forbidden	credential without access to the resource
`404`	Not found	resource missing or not yours
`409`	Conflict	address already exists; `quote_already_used`; `quote_expired`
`422`	Unprocessable	order route not tradable
`500`	Internal error	—
`503`	Service unavailable	`price_unavailable`; pricing temporarily unavailable

​1. Base URL

​2. Authentication

​3. Conventions

​4. The partner flow at a glance

​5. Addresses

​GET /otc/addresses

​GET /otc/addresses/{id}

​POST /otc/addresses

​PUT /otc/addresses/{id}

​DELETE /otc/addresses/{id}

​Address object

​6. Orders

​POST /otc/orders/quote — create a quote (unconfirmed order)

​GET /otc/orders

​GET /otc/orders/{id}

​POST /otc/orders/{id}/confirm — confirm a quoted order

​POST /otc/orders/{id}/cancel — cancel an order

​Order response shapes

​7. Funding activity & balances

​GET /funding/funding-activity — the funding-activity feed

​GET /funding/balances — balances

​8. Error reference