Create a transfer between the client's own accounts

Price a move between two accounts the client owns, reserve it idempotently and return the approval to sign. authorization says what that approval covers: a debit of the client’s wallet that funds the move, or an intent its smart wallet signs so the backend can settle it.

POST /swaps

Create a transfer between the client's own accounts

cURL

curl --request POST \
  --url https://api.example.com/swaps \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "publicKey": "<string>"
}
'

201

{
  "id": "swp_9f2c1ab84d7e4f1fa3c65b0e7d9a2c41",
  "status": "awaitingSignature",
  "idempotencyKey": "<string>",
  "sourceAccount": "USDC",
  "destinationAccount": "USDC",
  "quote": {
    "fromAmount": "500.00",
    "fromCurrency": "<string>",
    "toAmount": "500.00",
    "toCurrency": "<string>",
    "rate": "500.00",
    "feeAmount": "500.00",
    "feeCurrency": "<string>",
    "minimumToAmount": "500.00",
    "estimated": false,
    "etaHours": 123,
    "expiresAt": "2023-11-07T05:31:56Z"
  },
  "authorization": "debit",
  "approval": {
    "id": "<string>",
    "payload": "<string>",
    "expiresAt": "2023-11-07T05:31:56Z"
  },
  "debit": {
    "address": "<string>",
    "amount": "500.00",
    "amountAtomic": "<string>",
    "token": "<string>",
    "chainId": 123
  },
  "intent": {
    "digest": "<string>",
    "settles": "<string>"
  }
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

X-Hevn-Account · string | null

The client account to act for, as a cl_… id. Omit it to act as yourself.

Example:

"cl_9f2c1ab84d7e4f1fa3c65b0e7d9a2c41"

x-api-key · string | null

Idempotency-Key · string | null

Your own key for this write, ^[A-Za-z0-9._:-]{1,128}$. A retry with the same key replays the first answer; the same key with a different request is refused.

Example:

"po-inv-2026-114"

Body

application/json

sourceAccount · enum<string> · required

Account the money leaves.

Available options: USDC, EURC, FDIC_USD

destinationAccount · enum<string> · required

Account the money lands on.

Available options: USDC, EURC, FDIC_USD

publicKey · string · required

Base64 DER SubjectPublicKeyInfo for the registered P-256 developer key.

Required string length: 1 - 512

amount · string | null

Exact amount to debit from the source account.

Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$

Example:

"500.00"

amountTo · string | null

Exact amount the destination account should receive.

Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$

Example:

"500.00"

Response

201

application/json

Successful Response

id · string · required

Stable public identifier for this swap.

Pattern: ^(?:swp_)?[A-Za-z0-9._:\-]{1,216}$

Example:

"swp_9f2c1ab84d7e4f1fa3c65b0e7d9a2c41"

status · enum<string> · required

Current public lifecycle status of the swap.

Available options: awaitingSignature, submitted, settled, failed

idempotencyKey · string · required

Caller-supplied key that makes an identical retry return this result.

sourceAccount · enum<string> · required

Account the money leaves.

Available options: USDC, EURC, FDIC_USD

destinationAccount · enum<string> · required

Account the money lands on.

Available options: USDC, EURC, FDIC_USD

quote · SwapQuoteView · object · required

Price, fee and conversion terms fixed for this swap.

Show child attributes

authorization · enum<string> · required

Whether the approval authorizes a balance debit or a signature over the swap's terms.

Available options: debit, intent

approval · ApprovalView · object · required

Authorization to sign with the developer key before settlement.

Show child attributes

debit · DebitView · object | null

Exact on-chain debit used to fund this swap.

Show child attributes

intent · IntentView · object | null

Terms authorized by the signature, when this swap is not funded by a debit.

Show child attributes