Skip to main content

Documentation Index

Fetch the complete documentation index at: https://musubinetwork.com/llms.txt

Use this file to discover all available pages before exploring further.

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

​
Endpoints

MethodEndpointDescription
POST/api/v1/ordersCreate a new FX order
GET/api/v1/ordersList your orders (filterable, paginated)
GET/api/v1/orders/{intent_id}Get order by ID
POST/api/v1/orders/{intent_id}/cancelCancel a PENDING or QUOTED order
GET/api/v1/orders/{intent_id}/quotesList quotes for an order
POST/api/v1/orders/{intent_id}/quotes/{quote_id}/acceptAccept a quote
GET/api/v1/orders/eventsReal-time SSE event stream
GET/api/v1/dashboard/statsOrder counts and settlement volume
All endpoints require JWT authentication (except /health and /auth/token). See Authentication and API Conventions for details on headers, pagination, error handling, and response envelopes.

​
Quick Example: Order to Settlement

​
1. Create an Order

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",
    "kyc_aml_ref": "c3d4e5f6-7890-1234-abcd-ef0123456789",
    "jurisdiction_sender": "JP",
    "jurisdiction_receiver": "KR",
    "memo": "Monthly settlement - March 2025"
  }'
Response: order in PENDING status with intent_id assigned.

​
2. Accept a Quote

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: 
{
  "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",
    "kyc_aml_ref": "c3d4e5f6-7890-1234-abcd-ef0123456789",
    "jurisdiction_sender": "JP",
    "jurisdiction_receiver": "KR"
  },
  "meta": {
    "request_id": "req_e5f6a7b8",
    "timestamp": "2025-03-15T09:00:15.100Z"
  }
}

​
Order Status Lifecycle

TransitionTrigger
PENDING -> QUOTEDQuote accepted via API
QUOTED -> EXECUTINGMusubi begins atomic settlement (automatic)
EXECUTING -> SETTLEDAll four DvP legs complete (automatic)
PENDING -> EXPIREDexpires_at reached without accepted quote
QUOTED -> EXPIREDQuote’s valid_until passed before settlement
PENDING/EXECUTING -> FAILEDValidation or settlement failure

​
Failure Reasons

ReasonDescription
NO_QUOTENo market maker quoted before expiry
SLIPPAGEBest quote below source_amount_max
KYC_FAILKYC/AML validation failed
TIMEOUTSettlement window exceeded
REVERTDvP transaction reverted

​
Real-Time Events (SSE)

Connect to GET /api/v1/orders/events for real-time updates: 
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)`);
});
EventTrigger
order_updatedOrder status changed
quote_receivedNew quote on a PENDING order (sender only)
heartbeatKeepalive 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.