Swaps

A swap moves money between two accounts that the same owner holds, for example USDC to EURC. Create one with POST /dapi/v1/swaps and sign it with your developer key. A swap moves your own money. A session acting for a client can preview a swap but cannot create one, for either integration kind. sourceAccount and destinationAccount take an account key or the acc_… id of a sub account (Sub account moves).

Preview a swap

POST /dapi/v1/swaps/preview returns the best price among the routes that serve the pair. Preview has no side effects.

curl -s -X POST "$HEVN_API/swaps/preview" \
  -H "Authorization: Bearer $HEVN_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sourceAccount":"USDC","destinationAccount":"EURC","amount":"500.00"}'

priced = hevn.post("/swaps/preview", {
    "sourceAccount": "USDC",
    "destinationAccount": "EURC",
    "amount": "500.00",
})

const priced = await hevn.post("/swaps/preview", {
  sourceAccount: "USDC",
  destinationAccount: "EURC",
  amount: "500.00",
});

priced, err := api.Post("/swaps/preview", hevn.Body{
	"sourceAccount":      "USDC",
	"destinationAccount": "EURC",
	"amount":             "500.00",
})

Response: 200

{ "sourceAccount": "USDC",
  "destinationAccount": "EURC",
  "quote": { "fromAmount": "500.00", "fromCurrency": "USDC",
             "toAmount": "462.14", "toCurrency": "EURC",
             "rate": "0.924280", "feeAmount": "0.75", "feeCurrency": "USDC",
             "minimumToAmount": "461.21", "estimated": false,
             "expiresAt": "2026-09-20T18:12:41Z" } }

Fields: Price a transfer between the client’s own accounts.

Create and confirm

Call POST /dapi/v1/swaps with the preview body plus publicKey and an Idempotency-Key. It prices the swap again and returns the approval.

Response: 201, Location: /dapi/v1/swaps/swp_9f2c1ab84d

{ "id": "swp_9f2c1ab84d",
  "status": "awaitingSignature",
  "idempotencyKey": "swap-A-1187",
  "sourceAccount": "USDC",
  "destinationAccount": "EURC",
  "quote": { "fromAmount": "500.00", "fromCurrency": "USDC",
             "toAmount": "462.14", "toCurrency": "EURC",
             "rate": "0.924280", "feeAmount": "0.75", "feeCurrency": "USDC" },
  "authorization": "debit",
  "approval": { "id": "b1e7…", "payload": "eyJib2R5Ijp7…", "expiresAt": "2026-09-20T18:10:59Z" },
  "debit": { "address": "0x8c41…", "sourceAddress": "0x2f1c…",
             "amount": "500.00", "amountAtomic": "500000000",
             "token": "USDC", "chainId": 8453, "operation": { … } } }

When authorization is debit, compare debit.sourceAddress, debit.address, debit.amount and debit.token with the swap you meant, and check debit.operation, before you sign (Debit contents). Fields: Create a transfer between the client’s own accounts. Sign approval.payload and post it to POST /dapi/v1/swaps/{swapId}/confirm (Signing). Confirm returns 202 with a pollUrl. Read GET /dapi/v1/swaps/{swapId} until status is settled or failed. While the approval is open, retry as described in Retrying a confirm. Once the approval is used or expired, confirm returns 409 swap_not_confirmable, so read the swap.

Read a swap

GET /dapi/v1/swaps/{swapId} returns the status and the quote the swap was fixed at.

Response: 200

{ "id": "swp_9f2c1ab84d",
  "status": "settled",
  "sourceAccount": "USDC",
  "destinationAccount": "EURC",
  "quote": { "fromAmount": "500.00", "fromCurrency": "USDC",
             "toAmount": "462.14", "toCurrency": "EURC",
             "rate": "0.924280", "feeAmount": "0.75", "feeCurrency": "USDC" },
  "transactionHash": "0x7d2b…",
  "transactionId": "txn_5c9e2f…",
  "createdAt": "2026-09-20T18:08:44Z",
  "settledAt": "2026-09-20T18:09:12Z" }

A swap that involves an FDIC_* account has a transactionId once it is on the ledger. Between token accounts transactionId is null, so match the swap on transactionHash. Fields: Retrieve a transfer between the client’s own accounts. To pay out of FDIC_USD without a swap, see Payouts.

Sub account moves

A move is a swap with the acc_… id of a sub account as sourceAccount or destinationAccount. It uses the same routes, the same swp_… resource and the same confirm.

{ "sourceAccount": "USDC", "destinationAccount": "acc_5Jd8Qw2LmX", "amount": "250.00",
  "publicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE…" }

Rule	Detail
Pairs	The account key of a token and a sub account that holds it, or two sub accounts of the same token
Price	One for one, with no fee. `quote.toAmount` equals `quote.fromAmount`.
`authorization`	`debit` of the account the money leaves. `debit.sourceAddress` is that account and `debit.address` is the receiving account’s address.
Another pair	`409 account_destination_unsupported` into a sub account, `409 source_account_unsupported` out of one
External account	`404 account_not_found`. No move exists between a HEVN wallet and an external account.

The response and GET /dapi/v1/swaps/{swapId} return the ids as sent. The exit for a token a sub account does not hold, the RD rules and the ledger rows of a move are on Sub accounts.

Statuses

`status`	Meaning	Next
`awaitingSignature`	Created and not yet confirmed.	Sign and confirm.
`submitted`	Confirmed and settling.	Read the swap.
`settled`	Settlement completed.	n/a
`failed`	The swap did not settle.	Read `failure.code`.

Refusals

Error	Cause	Action
`400 invalid_request`	No route serves the pair.	Choose another pair of accounts.
`422 account_unavailable`	The owner does not hold the `FDIC_*` account.	Use an account from the balance.
`422 swap_route_unavailable`	The sandbox does not run a swap or preview between two account keys. It serves a move.	n/a
`403 account_not_controlled`	`POST /dapi/v1/swaps` or its confirm was called with a client in `X-Hevn-Account`.	Swap your own accounts. A client’s accounts cannot be swapped through the API.
`409 account_destination_unsupported`, `409 source_account_unsupported`	The pair is not a move a sub account can make.	See Sub account moves.
`404 account_not_found`	The `acc_…` id is unknown or names an external account.	Use a sub account of your own.
`409 swap_not_confirmable`	The approval was used or has expired.	Read the swap.

Other codes: Errors.

Start here

Core concepts

Clients

Move money

Ship it

Reference

Changelog