> ## Documentation Index
> Fetch the complete documentation index at: https://musubinetwork.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Endpoints, request/response examples, and SSE events for custodians.

This page covers the technical API details for your development team. For business context, see the preceding guide pages.

## Endpoints

| Method | Endpoint                                              | Description                                   |
| ------ | ----------------------------------------------------- | --------------------------------------------- |
| GET    | `/api/v1/orders`                                      | List custodied orders (filterable, paginated) |
| GET    | `/api/v1/orders/{intent_id}`                          | Get order by ID                               |
| POST   | `/api/v1/orders/{intent_id}/accept`                   | Accept an order proposal (sender custodian)   |
| GET    | `/api/v1/orders/{intent_id}/quotes`                   | List quotes for an order                      |
| POST   | `/api/v1/orders/{intent_id}/quotes/{quote_id}/accept` | Accept a quote (sender custodian)             |
| GET    | `/api/v1/orders/events`                               | Real-time SSE event stream                    |
| GET    | `/api/v1/dashboard/stats`                             | Order counts and settlement volume            |

All endpoints require JWT authentication (except `/health` and `/auth/token`). See [Authentication](/authentication) and [API Conventions](/api-conventions).

<Note>
  Only **sender custodians** can accept order proposals and quotes. Receiver custodians have read-only access to orders where they are the receiving custodian.
</Note>

## Quick Example: Review and Accept a Quote

### 1. List Pending Orders

```bash theme={null}
curl -H "Authorization: Bearer $TOKEN" \
  "https://your-backend.example.com/api/v1/orders?status=PENDING"
```

```json Response theme={null}
{
  "data": [
    {
      "intent_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "status": "PENDING",
      "sender_party_id": "SenderInstitution::209fa2c...b341",
      "sender_custodian_party_id": "CustodianA::209fa2c...b341",
      "source_currency": "JPYSC0",
      "target_amount": "100000",
      "target_currency": "USDCx",
      "source_amount_max": "12000000",
      "created_at": "2025-03-15T09:00:00.000Z",
      "expires_at": "2025-03-15T09:05:00.000Z"
    }
  ],
  "meta": { "request_id": "req_a1b2c3d4", "timestamp": "2025-03-15T09:00:01.000Z" },
  "pagination": { "page": 1, "page_size": 20, "total_items": 1, "total_pages": 1 }
}
```

### 2. Review Competing Quotes

```bash theme={null}
curl -H "Authorization: Bearer $TOKEN" \
  "https://your-backend.example.com/api/v1/orders/f47ac10b-58cc-4372-a567-0e02b2c3d479/quotes"
```

```json Response theme={null}
{
  "data": [
    {
      "quote_id": "a1b2c3d4-e5f6-7890-abcd-ef0123456789",
      "intent_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "market_maker_party_id": "MarketMaker::c4d5e6f7...8901",
      "fx_rate": "112.0",
      "source_amount": "11200000",
      "target_amount": "100000",
      "submitted_at": "2025-03-15T09:00:08.000Z",
      "valid_until": "2025-03-15T09:00:41.000Z",
      "status": "PENDING"
    }
  ],
  "meta": { "request_id": "req_b2c3d4e5", "timestamp": "2025-03-15T09:00:09.000Z" },
  "pagination": { "page": 1, "page_size": 20, "total_items": 1, "total_pages": 1 }
}
```

### 3. Accept the Best Quote

```bash theme={null}
curl -X POST \
  "https://your-backend.example.com/api/v1/orders/f47ac10b-58cc-4372-a567-0e02b2c3d479/quotes/a1b2c3d4-e5f6-7890-abcd-ef0123456789/accept" \
  -H "Authorization: Bearer $TOKEN"
```

```json Response theme={null}
{
  "data": {
    "intent_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "status": "QUOTED",
    "quote_id": "a1b2c3d4-e5f6-7890-abcd-ef0123456789",
    "fx_rate": "112.0",
    "source_amount_actual": "11200000",
    "quote_accepted_at": "2025-03-15T09:00:11.000Z"
  },
  "meta": { "request_id": "req_c3d4e5f6", "timestamp": "2025-03-15T09:00:11.100Z" }
}
```

The order is now **QUOTED**. Settlement proceeds automatically and completes in \~4 seconds.

### 4. Verify Settlement

Poll `GET /api/v1/orders/{intent_id}` until `status` is `SETTLED`:

```json theme={null}
{
  "data": {
    "intent_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "status": "SETTLED",
    "target_amount": "100000",
    "source_amount_actual": "11200000",
    "fx_rate": "112.0",
    "transaction_hash": "a3f2c1d9e8b74f6a2c1d9e8b74f6a2c14401",
    "settled_at": "2025-03-15T09:00:15.000Z"
  },
  "meta": { "request_id": "req_d4e5f6a7", "timestamp": "2025-03-15T09:00:15.100Z" }
}
```

## Real-Time Events (SSE)

Connect to `GET /api/v1/orders/events`:

```javascript theme={null}
const events = new EventSource(
  'https://your-backend.example.com/api/v1/orders/events'
);

events.addEventListener('order_updated', (e) => {
  const order = JSON.parse(e.data);
  console.log(`Order ${order.intent_id}: ${order.status}`);
});

events.addEventListener('quote_received', (e) => {
  const quote = JSON.parse(e.data);
  console.log(`Quote: ${quote.fx_rate} (${quote.target_amount} USDCx)`);
});
```

| Event            | Trigger                                         |
| ---------------- | ----------------------------------------------- |
| `order_updated`  | A custodied order changed status                |
| `quote_received` | New quote on a sender custodian's PENDING order |
| `heartbeat`      | Keepalive every 30 seconds                      |

Filter to a specific order: `?intent_id={uuid}`

## Full OpenAPI Specification

For complete request/response schemas, see the auto-generated [Custodian API Reference](/api-reference/custodian).