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). Funding endpoints wrap results as { "data": [...], "pagination": { page, limit, total, totalPages } }; GET /otc/addresses returns the same counters flat on the envelope: { "data": [...], "page", "limit", "total", "totalPages" }.
Timestamps are ISO-8601 strings (UTC).
Errors — the two endpoint groups use slightly different shapes:
- /otc endpoints return { "statusCode": number, "error": string, "message": string }, where error is the HTTP reason phrase (e.g. "Conflict") and machine-readable codes such as quote_already_used are carried in message.
- /funding endpoints return { "statusCode": number, "error": string, "message": string, "code": string }. Discriminate on code (VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, ENTITY_NOT_FOUND, AUTH_DEPENDENCY_UNAVAILABLE); the error field is not meaningful on this group.

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 → FULFILLED (a fully funded order may skip PARTIALLY_FILLED). After FULFILLED the payout runs: FULFILLED → PROCESSING_PAYOUT → SETTLED, with PAYOUT_FAILED reachable from PROCESSING_PAYOUT (payouts are retried, returning the order to PROCESSING_PAYOUT). Two more terminal states can appear:

CANCELLED — reachable from QUOTED, PENDING_FUNDING, and PARTIALLY_FILLED (the cancellable states).
EXPIRED — reachable from QUOTED, PENDING_FUNDING, and PARTIALLY_FILLED when the quote/order expiry elapses.

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: ERC20, Bitcoin, Liquid, or Liquid AMP — not a lowercase network name), status, asset, page, limit. 200 → { data: Address[], page, limit, total, totalPages } (flat envelope — see Conventions).

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

Partner keys may only update notes; changing the address string or its type requires an internal grant and returns 403. 200 → Address. 409 if the address is currently used in an active request, or if the change would duplicate an existing address.

`DELETE /otc/addresses/{id}`

204 No Content. 409 if the address is currently used in an active request, or is bound to a trading pair (remove or update the binding first).

`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 (the code string is carried in the error body’s message):

404 user_pair_not_found — no route configured for this asset pair.
409 user_pair_inactive — the route exists but is not currently tradable.
422 amount_below_min — the amount is below the pair’s minimum size.
503 price_unavailable / 503 price_stale — pricing cannot value the order right now; retry later.

`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. 409 if the order is not in a cancellable state (message: Order in status <STATUS> cannot be cancelled.).

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": 6,                     // 2 | 6 — display precision; USDT↔USTBL orders report 6
  "wallets": [
    {
      "label": "Funding wallet",
      "network": "ethereum",
      "address": "0xabc...5678"            // may be null while not yet resolved
    }
  ]
}

Each entry in wallets has exactly label, network, and address (nullable). The list carries the funding-side wallets followed by your payout wallet. OrderDetail (returned by quote/get) = OrderSummary plus:

{
  "flowType": "nb_api"
}

The funding wallet address in 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, payoutId, 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 (must be a UUID), date_from, date_to (ISO-8601; date_from must not be after date_to) — all optional — plus page and limit. 200 → { data: FundingActivityItem[], pagination }:

{
  "data": [
    {
      "funding_id": "….",
      "partner_id": "….",                  // may be null
      "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 or query parameter
`401`	Unauthorized	missing/invalid credential
`403`	Forbidden	credential without access to the resource
`404`	Not found	resource missing or not yours; `user_pair_not_found` (no route for the asset pair)
`409`	Conflict	address already exists; address in use / bound to a trading pair; order not in a cancellable state; `quote_already_used`; `quote_expired`; `user_pair_inactive`
`422`	Unprocessable	`amount_below_min` — amount below the pair’s minimum size
`500`	Internal error	—
`503`	Service unavailable	`price_unavailable` / `price_stale` (pricing temporarily unavailable); funding endpoints when their auth dependency is unreachable

On /otc endpoints the code strings above (quote_expired, price_unavailable, …) arrive in the error body’s message field; on /funding endpoints use the code field (see Conventions).

​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