Send transfers

POST /transfer moves money out of a custodial wallet on either rail. One field (type) decides whether the amount is public or encrypted.

type: "public"

A standard ERC-20 transfer of the test stablecoin. Amount visible on-chain, cheapest and fastest.

type: "private"

A cAROUSD confidentialTransfer. The amount is FHE-encrypted; observers see the transfer, never the value.

Make the call

curl -s "$BASE/transfer" \
  -H "Authorization: Bearer $KEY" \
  -H "content-type: application/json" \
  -d "{\"walletId\":\"$WALLET\",\"to\":\"0x52aE…9021\",\"amount\":\"25\",\"type\":\"private\"}"

curl -s "$BASE/transfer" \
  -H "Authorization: Bearer $KEY" \
  -H "content-type: application/json" \
  -d "{\"walletId\":\"$WALLET\",\"to\":\"0x52aE…9021\",\"amount\":\"25\",\"type\":\"public\"}"

{
  "ok": true,
  "data": {
    "transaction": {
      "id": "cktxn0003…",
      "type": "PRIVATE_TRANSFER",
      "status": "QUEUED",
      "amount": "25.00",
      "token": "cAROUSD",
      "txHash": null,
      "explorerUrl": null,
      "fromAddress": "0x8Ba1…BA72",
      "toAddress": "0x52aE…9021",
      "error": null,
      "errorCode": null,
      "walletId": "ckwlt0001…",
      "createdAt": "2026-08-13T09:45:00.000Z",
      "updatedAt": "2026-08-13T09:45:00.000Z"
    }
  }
}

The 201 confirms the transfer is validated and queued. A background worker signs and broadcasts it (PENDING, txHash set) and tracks the receipt; poll to completion until CONFIRMED or FAILED.

Request fields

Field	Required	Notes
`walletId`	✓	Must be a custodial wallet; AroPay signs with its key. External wallets are rejected with `400`.
`to`	✓	Recipient address (`0x…`, checksummed). Counterparties often share theirs as a .nota address card; the address inside is what you pass here.
`amount`	✓	Decimal string in human units, e.g. `"25"` or `"25.50"`.
`type`	✓	`"public"` or `"private"`.

The sending wallet needs a sufficient balance on the matching rail: public stablecoin for public, cAROUSD for private (mint first if needed), plus ETH for gas.

Privacy characteristics

For private transfers, the amount is encrypted client-side of the chain; that is, AroPay’s background worker produces the encrypted input and proof server-side and submits it after your request has returned. On-chain observers see sender, recipient, and the fact of a transfer; the value stays ciphertext. The recipient (or AroPay, for custodial recipients) decrypts their updated balance through the relayer.

Private transfers cost more gas and take a bit longer than public ones; encrypted inputs are bigger and verification is heavier. Budget for that in UX, not in correctness.

Failure modes

Request problems fail the POST; execution problems fail the transaction row later (status: "FAILED" with error and errorCode). A failed transfer never moved funds.

Response	Meaning
`400 invalid_recipient`	`to` is not a valid address, or is the sending wallet itself.
`400 invalid_amount` / `validation_error`	Malformed amount.
`400 insufficient_balance` (`public` only)	The wallet’s public stablecoin balance is below `amount` at request time.
`400 wallet_not_custodial`	`walletId` refers to an external wallet.
`503 fhe_*` (`private` only)	The confidential rail is not configured on this deployment; nothing was queued.
`FAILED` with `errorCode: "insufficient_confidential_balance"`	`private`: the decrypted cAROUSD balance (minus other queued debits) cannot cover `amount`. The worker re-checks for a few minutes before failing, so a just-confirmed mint is picked up.
`FAILED` with `errorCode: "insufficient_balance"`	`public`: the balance dropped below `amount` before the worker submitted.
`FAILED` with `errorCode: "transfer_failed"`	The transaction reverted on-chain; `error` carries the revert context.

Get started

Core concepts

Guides

Security & access

Support

Send transfers

type: "public"

type: "private"

Make the call

Request fields

Privacy characteristics

Failure modes

type: "public"

type: "private"

​Make the call

​Request fields

​Privacy characteristics

​Failure modes

Make the call

Request fields

Privacy characteristics

Failure modes