Skip to main content
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": "SenderCustodian::209fa2c...b341",
    "intent_signature": "3045022100af...2f",
    "receiver_party_id": "ReceiverBank::8bc31d4...a902",
    "receiver_custodian_party_id": "ReceiverCustodian::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.