> ## 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, quote status flows, and SSE events.

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/quote-requests`                    | List active anonymized RFQs                 |
| GET    | `/api/v1/quote-requests/{intent_id}`        | Get quote request details                   |
| POST   | `/api/v1/quote-requests/{intent_id}/quotes` | Submit a quote                              |
| GET    | `/api/v1/quote-requests/{intent_id}/quotes` | List your quotes for a request              |
| GET    | `/api/v1/quotes`                            | List all your quotes (filterable by status) |
| GET    | `/api/v1/settlements`                       | List your won settlements                   |
| GET    | `/api/v1/settlements/{intent_id}`           | Get settlement details                      |
| GET    | `/api/v1/events`                            | Real-time SSE event stream                  |
| GET    | `/api/v1/dashboard/stats`                   | Quoting performance and volume stats        |

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

## Quick Example: Quote to Settlement

### 1. List Active RFQs

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

```json Response theme={null}
{
  "data": [
    {
      "intent_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "created_at": "2025-03-15T09:00:00.000Z",
      "expires_at": "2025-03-15T09:05:00.000Z",
      "source_currency": "JPYSC0",
      "target_amount": "100000",
      "target_currency": "USDCx"
    }
  ],
  "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. Submit a Quote

```bash theme={null}
curl -X POST \
  "https://your-backend.example.com/api/v1/quote-requests/f47ac10b-58cc-4372-a567-0e02b2c3d479/quotes" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fx_rate": "112.0",
    "target_amount": "11200000",
    "valid_until": "2025-03-15T09:00:41.000Z"
  }'
```

```json 201 Created theme={null}
{
  "data": {
    "quote_id": "a1b2c3d4-e5f6-7890-abcd-ef0123456789",
    "intent_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "fx_rate": "112.0",
    "target_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:08.100Z" }
}
```

### 3. Check Quote Outcome

Poll `GET /api/v1/quotes?status=ACCEPTED` or subscribe to SSE events.

### 4. View Settlement Details

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

```json Response theme={null}
{
  "data": {
    "intent_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "source_currency": "JPYSC0",
    "target_amount": "100000",
    "target_currency": "USDCx",
    "source_amount_actual": "11200000",
    "fx_rate": "112.0",
    "quote_id": "a1b2c3d4-e5f6-7890-abcd-ef0123456789",
    "mm_quoted_source_amount": "11200000",
    "mm_delivered_target_amount": "100000",
    "transaction_hash": "a3f2c1d9e8b74f6a2c1d9e8b74f6a2c14401",
    "settled_at": "2025-03-15T09:00:15.000Z"
  },
  "meta": { "request_id": "req_c3d4e5f6", "timestamp": "2025-03-15T09:00:16.000Z" }
}
```

## Quote Status Flow

```
PENDING ──────> ACCEPTED  (you won)
   │
   ├──────> REJECTED  (another MM won)
   │
   └──────> EXPIRED   (valid_until passed)
```

## Real-Time Events (SSE)

Connect to `GET /api/v1/events` (note: `/events`, not `/orders/events`):

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

events.addEventListener('quote_request_new', (e) => {
  const request = JSON.parse(e.data);
  // Your pricing engine evaluates and submits a quote
});

events.addEventListener('quote_accepted', (e) => {
  const data = JSON.parse(e.data);
  console.log(`Won: ${data.intent_id} at rate ${data.fx_rate}`);
});

events.addEventListener('quote_rejected', (e) => {
  const data = JSON.parse(e.data);
  console.log(`Lost: ${data.intent_id}`);
});

events.addEventListener('settlement_completed', (e) => {
  const settlement = JSON.parse(e.data);
  console.log(`Settled: ${settlement.transaction_hash}`);
});
```

| Event                   | Trigger                             |
| ----------------------- | ----------------------------------- |
| `quote_request_new`     | New anonymized RFQ available        |
| `quote_request_expired` | An RFQ expired (no longer quotable) |
| `quote_accepted`        | Your quote was selected             |
| `quote_rejected`        | Another MM's quote was selected     |
| `settlement_completed`  | A trade you won has settled         |
| `heartbeat`             | Keepalive every 30 seconds          |

## Full OpenAPI Specification

For complete request/response schemas, see the auto-generated [Market Maker API Reference](/api-reference/market-maker).