> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.nexbridge.finance/llms.txt
> Use this file to discover all available pages before exploring further.

# Partner API Reference

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:

```text theme={null}
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:

```text theme={null}
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

```text theme={null}
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`

Register an address. One of `type` or `network` is required.

```json theme={null}
{
  "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}`

```json theme={null}
{ "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`).

```json theme={null}
{
  "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):

```json theme={null}
{
  "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:

```json theme={null}
{
  "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 }`:

```json theme={null}
{
  "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 }`:

```json theme={null}
{
  "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          |