Swaps

A swap moves money between two accounts the same client owns. Nobody else is paid, so there is no contact and no beneficiary: POST /dapi/v1/swaps prices and reserves the move, POST /dapi/v1/swaps/{swapId}/confirm authorizes it. A client holding euros that owes dollars swaps before it pays out, and the money never leaves its own name.

northwind = hevn.acting_as(CLIENT_ID)

swap = northwind.post("/swaps", {
    "sourceAccount": "USDC",
    "destinationAccount": "EURC",
    "amount": "500.00",
    "publicKey": key.public_key,
}, idempotency_key="swap-A-1187")

signature = key.sign_payload(swap["approval"]["payload"])
receipt = northwind.confirm_until_settled(f"/swaps/{swap['id']}/confirm", signature)

const northwind = hevn.actingAs(clientId);

const swap = await northwind.post("/swaps", {
  sourceAccount: "USDC",
  destinationAccount: "EURC",
  amount: "500.00",
  publicKey: key.publicKey,
}, { idempotencyKey: "swap-A-1187" });

const signature = key.signPayload(swap.approval.payload);
const receipt = await northwind.confirmUntilSettled(`/swaps/${swap.id}/confirm`, signature);

northwind := api.ActingAs(clientID)

swap, err := northwind.Post("/swaps", hevn.Body{
	"sourceAccount":      "USDC",
	"destinationAccount": "EURC",
	"amount":             "500.00",
	"publicKey":          key.PublicKey,
}, hevn.IdempotencyKey("swap-A-1187"))

signature, err := key.SignPayload(swap.Str("approval.payload"))
receipt, err := northwind.ConfirmUntilSettled("/swaps/"+swap.Str("id")+"/confirm", signature)

Examples use the client from HTTP client. acting_as sets the header that picks whose money moves: Send X-Hevn-Account: cl_… with your own access token to act for one client. On a resource route like GET /banks the header is optional: omit it and the call acts on your integrator account instead. The singular /client* routes require it — the header is the only thing that names the account — and /clients and /escrow* refuse it.

curl "$HEVN_API/banks" \
  -H "Authorization: Bearer $HEVN_ACCESS_TOKEN" \
  -H "X-Hevn-Account: $HEVN_CLIENT_ID"

northwind = hevn.acting_as(CLIENT_ID)
rails = northwind.get("/banks")

const northwind = hevn.actingAs(clientId);
const rails = await northwind.get("/banks");

northwind := api.ActingAs(clientID)
rails, err := northwind.Get("/banks")

The whole table — where the header is optional, where it is required and where it is refused — is in Sessions.

The accounts

Both sides are named from one vocabulary, the same one the balance reads back and a payout’s sourceAccount takes. USDC and EURC are the stablecoins on the client’s wallet; FDIC_USD is dollars a partner bank holds for it:

Account	Where the money is	Currency
`USDC`	the client’s Base smart wallet	USD
`EURC`	the same smart wallet	EUR
`FDIC_USD`	a virtual account a partner bank holds for the client	USD

The two sides must differ, and both must be accounts that client actually holds. An account it does not hold is 422 account_unavailable — a client with no custodial virtual account cannot name FDIC_USD. A pair nothing can serve right now is 422 swap_route_unavailable.

Price it first

POST /dapi/v1/swaps/preview takes the same accounts and amount without a publicKey, compares every route that can serve the pair, and answers the best one. It reserves nothing, signs nothing and returns no swapId, so it is safe to call on every keystroke of a form.

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

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

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

priced, err := northwind.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" } }

Pin one side and one only: amount is what leaves the source account, amountTo is what has to arrive on the destination. Sending both, or neither, is 422 validation_failed. minimumToAmount is the floor a route with slippage guarantees; estimated: true marks a move whose delivered amount is only known on arrival, and then etaHours says how long that takes. A locked price carries expiresAt and nothing else has to be read.

Reserve and sign

POST /dapi/v1/swaps prices the move again, fixes it, and returns the approval to sign. The response tells you what that approval authorizes:

`authorization`	What it means	What else is on the response
`debit`	the move is funded by sending tokens out of the client’s wallet	`debit` — the exact address, amount and token that will leave
`intent`	the move is settled by HEVN against the client’s own signature, with nothing leaving the wallet	`intent` — the EIP-712 `digest` of the terms being authorized

Either way you sign approval.payload and post it to the same confirm route. The difference is what HEVN does with the co-signature, not what your code does with 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…", "amount": "500.00", "amountAtomic": "500000000",
             "token": "USDC", "chainId": 8453 } }

When authorization is debit, check debit before you sign — it is decoded out of the operation itself, not echoed from your request, and it is the one cross-check a signer has (Signing).

import base64
from cryptography.hazmat.primitives import hashes
from cryptography.hazmat.primitives.asymmetric import ec


def sign_bytes(key, message: bytes) -> str:
    """base64(DER ECDSA P-256 / SHA-256) over exactly these bytes."""
    return base64.b64encode(key.sign(message, ec.ECDSA(hashes.SHA256()))).decode()


def sign_payload(key, payload_b64: str) -> str:
    return sign_bytes(key, base64.b64decode(payload_b64))

import { sign } from "node:crypto";

export function signBytes(key, message) {
  return sign("sha256", message, { key, dsaEncoding: "der" }).toString("base64");
}

export function signPayload(key, payloadB64) {
  return signBytes(key, Buffer.from(payloadB64, "base64"));
}

func SignBytes(key *ecdsa.PrivateKey, message []byte) (string, error) {
	digest := sha256.Sum256(message)
	der, err := ecdsa.SignASN1(rand.Reader, key, digest[:])
	if err != nil {
		return "", err
	}
	return base64.StdEncoding.EncodeToString(der), nil
}

func SignPayload(key *ecdsa.PrivateKey, payloadB64 string) (string, error) {
	message, err := base64.StdEncoding.DecodeString(payloadB64)
	if err != nil {
		return "", err
	}
	return SignBytes(key, message)
}

Then confirm, and keep confirming while it is still in flight:

CONFIRM_AGAIN = {"funding_in_progress", "bundler_rejected", "bundler_unavailable"}


class ReopenRequired(Exception):
    """The approval expired. Re-open the payment with the same Idempotency-Key."""


def confirm_until_settled(self, confirm_path: str, signature: str, *, deadline=180.0):
    """A method on Hevn. confirm_path is "/payouts/po_…/confirm" or an escrow action's confirm."""
    started, delay = time.monotonic(), 1.0
    while True:
        try:
            receipt = self.post(confirm_path, {"signature": signature})
            if receipt["status"] != "submitted":
                return receipt
            reason = "submitted"
        except HevnError as error:
            if error.code == "already_funded":
                return {"status": "settled", "transactionHash": error.details.get("transactionHash")}
            if error.code == "funding_attempt_expired":
                raise ReopenRequired(confirm_path) from error
            if error.code not in CONFIRM_AGAIN:
                raise
            reason = error.code
        if time.monotonic() - started > deadline:
            raise TimeoutError(f"{confirm_path} still {reason} after {deadline:.0f}s")
        time.sleep(delay)
        delay = min(delay * 2, 8.0)

const CONFIRM_AGAIN = new Set(["funding_in_progress", "bundler_rejected", "bundler_unavailable"]);

export class ReopenRequired extends Error {}

// A method on Hevn. confirmPath is "/payouts/po_…/confirm" or an escrow action's confirm.
export async function confirmUntilSettled(confirmPath, signature, { deadline = 180_000 } = {}) {
  const until = Date.now() + deadline;
  let delay = 1_000;
  for (;;) {
    let reason = "submitted";
    try {
      const receipt = await this.post(confirmPath, { signature });
      if (receipt.status !== "submitted") return receipt;
    } catch (error) {
      if (error.code === "already_funded") {
        return { status: "settled", transactionHash: error.details.transactionHash };
      }
      if (error.code === "funding_attempt_expired") throw new ReopenRequired(confirmPath);
      if (!CONFIRM_AGAIN.has(error.code)) throw error;
      reason = error.code;
    }
    if (Date.now() > until) throw new Error(`${confirmPath} still ${reason}`);
    await new Promise((wake) => setTimeout(wake, delay));
    delay = Math.min(delay * 2, 8_000);
  }
}

var confirmAgain = map[string]bool{
	"funding_in_progress": true, "bundler_rejected": true, "bundler_unavailable": true,
}

var ErrReopenRequired = errors.New("hevn: approval expired, re-open with the same Idempotency-Key")

// confirmPath is "/payouts/po_…/confirm" or an escrow action's confirm.
func (c *Client) ConfirmUntilSettled(confirmPath, signature string) (Payload, error) {
	until, delay := time.Now().Add(3*time.Minute), time.Second
	for {
		receipt, err := c.Post(confirmPath, Body{"signature": signature})
		var apiErr *APIError
		switch {
		case err == nil && receipt.Str("status") != "submitted":
			return receipt, nil
		case err == nil: // submitted: no receipt yet, confirm again
		case !errors.As(err, &apiErr):
			return nil, err
		case apiErr.Code == "already_funded":
			return Payload{"status": "settled", "transactionHash": apiErr.Details["transactionHash"]}, nil
		case apiErr.Code == "funding_attempt_expired":
			return nil, ErrReopenRequired
		case !confirmAgain[apiErr.Code]:
			return nil, err
		}
		if time.Now().After(until) {
			return nil, fmt.Errorf("hevn: %s did not settle in time", confirmPath)
		}
		time.Sleep(delay)
		if delay < 8*time.Second {
			delay *= 2
		}
	}
}

A confirm answers 200 when settlement landed inside the request and 202 submitted when it did not; in the second case pollUrl names the read route. Confirm is single use: the same signature a second time is 409 funding_attempt_expired on a debit swap and 410 approval_expired on an intent one. Either way the move already happened, and the way to check on it is GET /dapi/v1/swaps/{swapId}, never another confirm.

Read it back

GET /dapi/v1/swaps/{swapId} carries the lifecycle, the accounts it ran between, the terms it was fixed at, and transactionId once the move is on the client’s ledger.

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 is not a second source of truth about money: both sides of it are ordinary ledger rows, so GET /dapi/v1/transactions shows the result without reading this route at all (Balances and transactions).

Retries

Derive Idempotency-Key from an id your own system already owns, pass it in from the caller, and keep it identical across every retry of the same payment.

key = f"payout-{invoice.id}"  # "payout-INV-2026-114"
northwind.post("/payouts", payout, idempotency_key=key)

const key = `payout-${invoice.id}`;
await northwind.post("/payouts", payout, { idempotencyKey: key });

key := "payout-" + invoice.ID
northwind.Post("/payouts", payout, hevn.IdempotencyKey(key))

Never generate the key inside the helper that sends the request, and never rotate it on a retry — both turn one payment into two. The format and the replay windows are in Conventions. The key names the move. A retry with the same key returns the swap it already created, with Idempotency-Replayed: true; the same key with different accounts or a different amount is 409 idempotency_key_reused, which is the guarantee that a repeated call is never a second conversion.

Paying straight out of the custodial balance

A client that holds FDIC_USD does not have to swap before it pays. POST /dapi/v1/payouts with "sourceAccount": "FDIC_USD" spends that balance directly: the payout is authorized by an intent signature instead of a debit, so the response carries authorization: "intent" and no debit, and confirm is unchanged (Payouts). Use a swap when the client wants the money on its wallet, and a payout when it wants a beneficiary paid.

In the sandbox

Swaps are the one money route the sandbox does not serve. The emulated chain has no exchange venue behind it and the emulator issues no custodial dollar balance, so POST /dapi/v1/swaps there answers a refusal rather than a quote. Build against the contract on this page and exercise it in production (Sandbox).

Next: Balances and transactions

Read a client’s balance, walk its ledger with a cursor, export a statement.

Start here

Core concepts

Onboard a client

Move money

Escrow

Ship it

Reference

The accounts

Price it first

Reserve and sign

Read it back

Retries

Paying straight out of the custodial balance

In the sandbox

Next: Balances and transactions

​The accounts

​Price it first

​Reserve and sign

​Read it back

​Retries

​Paying straight out of the custodial balance

​In the sandbox

Next: Balances and transactions

The accounts

Price it first

Reserve and sign

Read it back

Retries

Paying straight out of the custodial balance

In the sandbox