> ## 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, order lifecycle, and real-time events.

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

## Endpoints

| Method | Endpoint                                              | Description                              |
| ------ | ----------------------------------------------------- | ---------------------------------------- |
| POST   | `/api/v1/orders`                                      | Create a new FX order                    |
| GET    | `/api/v1/orders`                                      | List your orders (filterable, paginated) |
| GET    | `/api/v1/orders/{intent_id}`                          | Get order by ID                          |
| POST   | `/api/v1/orders/{intent_id}/cancel`                   | Cancel a PENDING or QUOTED order         |
| 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                           |
| 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) for details on headers, pagination, error handling, and response envelopes.

## Quick Example: Order to Settlement

### 1. Create an Order

```bash theme={null}
curl -X POST https://your-backend.example.com/api/v1/orders \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sender_custodian_party_id": "CustodianA::209fa2c...b341",
    "intent_signature": "3045022100af...2f",
    "receiver_party_id": "InstitutionB::8bc31d4...a902",
    "receiver_custodian_party_id": "CustodianB::5de09a1...c774",
    "source_contract_id": "00a3f7c2...1d83#0",
    "source_currency": "JPYSC0",
    "target_amount": "100000",
    "target_currency": "USDCx",
    "source_amount_max": "12000000",
    "memo": "Monthly settlement - March 2025"
  }'
```

Response: order in `PENDING` status with `intent_id` assigned.

### 2. Accept a Quote

```bash theme={null}
curl -X POST \
  "https://your-backend.example.com/api/v1/orders/{intent_id}/quotes/{quote_id}/accept" \
  -H "Authorization: Bearer $TOKEN"
```

Response: order transitions to `QUOTED` with `fx_rate`, `source_amount_actual`, and `market_maker_party_id` populated.

### 3. 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",
    "source_currency": "JPYSC0",
    "target_amount": "100000",
    "target_currency": "USDCx",
    "source_amount_actual": "11200000",
    "fx_rate": "112.0",
    "transaction_hash": "a3f2c1d9e8b74f6a2c1d9e8b74f6a2c14401",
    "settled_at": "2025-03-15T09:00:15.000Z"
  },
  "meta": {
    "request_id": "req_e5f6a7b8",
    "timestamp": "2025-03-15T09:00:15.100Z"
  }
}
```

## Order Status Lifecycle

```mermaid actions=false theme={null}
graph LR
  PENDING --> QUOTED
  QUOTED --> EXECUTING
  EXECUTING --> SETTLED
  PENDING -.->|no quote before expiry| EXPIRED
  PENDING -.->|validation failure| FAILED
  QUOTED -.->|quote validity passed| EXPIRED
```

| Transition                  | Trigger                                        |
| --------------------------- | ---------------------------------------------- |
| PENDING -> QUOTED           | Quote accepted via API                         |
| QUOTED -> EXECUTING         | Musubi begins atomic settlement (automatic)    |
| EXECUTING -> SETTLED        | All four DvP legs complete (automatic)         |
| PENDING -> EXPIRED          | `expires_at` reached without accepted quote    |
| QUOTED -> EXPIRED           | Quote's `valid_until` passed before settlement |
| PENDING/EXECUTING -> FAILED | Validation or settlement failure               |

### Failure Reasons

| Reason               | Description                          |
| -------------------- | ------------------------------------ |
| `NO_QUOTE`           | No market maker quoted before expiry |
| `SLIPPAGE`           | Best quote below `source_amount_max` |
| `TIMEOUT`            | Settlement window exceeded           |
| `REVERT`             | DvP transaction reverted             |
| `USER_CANCELLED`     | Order cancelled by the sender        |
| `OPERATOR_WITHDRAWN` | Order withdrawn by the operator      |

## Real-Time Events (SSE)

Connect to `GET /api/v1/orders/events` for real-time updates:

```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`  | Order status changed                       |
| `quote_received` | New quote on a PENDING order (sender only) |
| `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 [Institution API Reference](/api-reference/institution).