Exchanges

Exchanges enable currency trades by moving assets between platform accounts denominated in different currencies. Currently, one side of every exchange must be a stablecoin.

Endpoints

POST /exchanges Create exchange (market) POST /exchanges/{id}/accept Accept exchange GET /exchanges/{id} Retrieve exchange

POST /exchanges

Create a market exchange to trade between two currencies.

Request Body

Field	Type	Description
`source_account_id` required	string	Source account ID (funds debited from)
`destination_account_id` required	string	Destination account ID (funds credited to)
`action` required	string	FIX_SOURCE (sell) or FIX_DESTINATION (buy)
`amount` required	string	Amount (source or destination based on action)

Example Request (Sell USD for USDC)

Request

{
  "source_account_id": "acc_usd_123",
  "destination_account_id": "acc_usdc_456",
  "action": "FIX_SOURCE",
  "amount": "1000.00"
}

Example Request (Buy 500 USDC)

Request

{
  "source_account_id": "acc_usd_123",
  "destination_account_id": "acc_usdc_456",
  "action": "FIX_DESTINATION",
  "amount": "500.00"
}

Response

201 Created

{
  "id": "exch_888777666",
  "source_account_id": "acc_usd_123",
  "destination_account_id": "acc_usdc_456",
  "action": "FIX_SOURCE",
  "source_amount": "1000.00",
  "source_currency": "USD",
  "destination_amount": "998.50",
  "destination_currency": "USDC",
  "rate": "0.9985",
  "status": "QUOTED",
  "quote_expires_at": "2026-01-15T10:35:00Z",
  "created_at": "2026-01-15T10:30:00Z"
}

POST /exchanges/{id}/accept

Accept and execute an exchange at the quoted rate.

Request Body

Field	Type	Description
`maximum_slippage`	integer	Maximum slippage in basis points (default: 100 = 1%)

Example Request

Request

{
  "maximum_slippage": 50
}

Response

200 OK

{
  "id": "exch_888777666",
  "source_account_id": "acc_usd_123",
  "destination_account_id": "acc_usdc_456",
  "action": "FIX_SOURCE",
  "source_amount": "1000.00",
  "source_currency": "USD",
  "destination_amount": "998.50",
  "destination_currency": "USDC",
  "rate": "0.9985",
  "status": "EXECUTED",
  "created_at": "2026-01-15T10:30:00Z",
  "accepted_at": "2026-01-15T10:31:00Z",
  "executed_at": "2026-01-15T10:31:00Z"
}

Slippage Handling

Slippage applies only to market exchanges with FIX_DESTINATION action:

Default maximum slippage is 100 basis points (1%)
If actual price variance exceeds slippage, the trade is cancelled
Unused slippage buffer is credited back as a MARKET_ADJUSTMENT transaction
Lower slippage reduces required funds but increases rejection risk

GET /exchanges/{id}

Retrieve details of a specific exchange.

Response

200 OK

{
  "id": "exch_888777666",
  "source_account_id": "acc_usd_123",
  "destination_account_id": "acc_usdc_456",
  "action": "FIX_SOURCE",
  "source_amount": "1000.00",
  "source_currency": "USD",
  "destination_amount": "998.50",
  "destination_currency": "USDC",
  "rate": "0.9985",
  "fee": "1.50",
  "status": "EXECUTED",
  "source_transaction_id": "txn_src_001",
  "destination_transaction_id": "txn_dst_001",
  "created_at": "2026-01-15T10:30:00Z",
  "accepted_at": "2026-01-15T10:31:00Z",
  "executed_at": "2026-01-15T10:31:00Z"
}

Exchange Status Values

Status	Description
`QUOTED`	Quote generated, awaiting acceptance
`EXECUTED`	Exchange completed successfully
`EXPIRED`	Quote expired before acceptance
`FAILED`	Exchange failed (e.g., slippage exceeded)
`CANCELLED`	Exchange was cancelled

Action Types

Action	Description
`FIX_SOURCE`	Debit fixed amount from source; quote shows destination amount ("selling")
`FIX_DESTINATION`	Credit fixed amount to destination; quote shows source amount ("buying")