Sign in

v1

latestOpenAPI 3.0.02026-07-24103118224.7 KB
Swap

Create a swap

Initiates a swap between USDC and EURC using the merchant's custodial wallet balance. Exactly one of amount (in cents) or max: true must be provided. The response is returned as soon as the swap is accepted; settlement is asynchronous — poll GET /api/swap/{id} or GET /api/swap/in-progress to follow progress. A merchant can only have one in-progress swap at a time.

post/api/swap

Request body

fromCurrency'USDC' | 'EURC' required
toCurrency'USDC' | 'EURC' required
amountnumber

Amount in cents (smallest unit)

maxboolean

Use full available source balance (server-resolved amount)

Response

Swap accepted and pipeline initiated

idstring required
userIdstring required
fromCurrency'USDC' | 'EURC' required
toCurrency'USDC' | 'EURC' required
amountnumber required

Source amount in cents (smallest unit of fromCurrency)

status'INITIATED' | 'PENDING' | 'PROCESSING' | 'COMPLETED' | 'FAILED' | 'CANCELED' | 'RETURNED' | 'REFUNDED' required

Merchant-facing status. Internal states (DEPOSIT_COMPLETED, AWAITING_LIQUIDATION) are collapsed to PENDING before being returned, so they will never appear on the wire.

context'bridge' | 'privy' nullable

Pipeline a swap follows: bridge (3 steps) or privy (2 steps).

toAmountInCentsnumber nullable

Final destination amount in cents (smallest unit of toCurrency). null until the swap settles.

createdAtstring date-time required
updatedAtstring date-time required

Example response

{
  "id": "swap_01JABCDEF0123456789XYZ",
  "userId": "usr_01JABCDEF0123456789XYZ",
  "fromCurrency": "USDC",
  "toCurrency": "EURC",
  "amount": 12345,
  "status": "PENDING",
  "context": "privy",
  "toAmountInCents": 11300
}