> ## Documentation Index > Fetch the complete documentation index at: https://docs.aropay.aro.media/llms.txt > Use this file to discover all available pages before exploring further. # Create letter > Turn a private cAROUSD transfer into a mailable letter. Escrows `amount` from a **custodial** wallet into the Aro Mail vault (a `confidentialTransfer` to the platform operator) and returns the letter with its one-time `claimCode`, the `claimUrl` the QR encodes (`https:///claim#`, code in the URL fragment), and the `pdfUrl` of the printable page. Defaults depend on the destination: domestic letters (destination = the deployment's home country, `US` by default) are `visible` and expire in 90 days; international letters are `sealed` and expire in 45 days. Addresses follow the destination's rules (US: two-letter state, ZIP or ZIP+4, 64-character lines; elsewhere `region` or `postal` is required). Amounts above the per-letter cap return `400 invalid_amount`; too many letters in flight return `429 letter_velocity_limit`. Blocks up to ~20 s for the escrow receipt. A letter returned as `DRAFT` with a `PENDING` escrow leg becomes `ESCROWED` on a later read once the receipt lands **and** the encrypted amount is verified; a reverted or clamped escrow becomes `FAILED` with nothing moved. If the escrow was broadcast but the bookkeeping after it failed, the call returns `502 escrow_unsettled` instead of the letter: the letter exists as `DRAFT` (find it in `GET /transfer/letter`), value has left the wallet, and reconciliation finishes it on the next read. Do not create it again. `claimCode` and `claimUrl` are returned only here and on `GET /transfer/letter/{id}`, only to the owner, and only while the letter is not terminal. Anyone holding the code can claim once. ## OpenAPI ````yaml /api-reference/openapi.yaml post /transfer/letter openapi: 3.1.0 info: title: AroPay API version: 1.0.0 description: | The AroPay API for orchestrating sealed, private payments on public ledgers, built on the Aro Confidential Rails (Zama Protocol FHE). Two environments run the same API: Production on Ethereum Mainnet (`aropay.aro.media`, real funds) and the Sandbox on Sepolia (`dev.aropay.aro.media`, test funds and a faucet). Integrations built against the sandbox carry over unchanged; the faucet (`POST /fund`) is sandbox-only and returns 404 on production. Every response (except the flat Sandbox probes) uses the shared envelope: `{ "ok": true, "data": … }` on success and `{ "ok": false, "error": { "code", "message", "details?" } }` on failure. Amounts are decimal strings in human units (e.g. `"125.50"`). Write requests must send `Content-Type: application/json`. contact: name: Aro Media url: https://aro.media servers: - url: https://aropay.aro.media/api/v1 description: Production (Ethereum Mainnet) - url: https://dev.aropay.aro.media/api/v1 description: Sandbox (Sepolia) - url: http://aropay.localhost:3000/api/v1 description: Local development security: - apiKeyAuth: [] - sessionCookie: [] tags: - name: Auth description: Password, TOTP, and passkey login; session inspection and logout. - name: Profile & security description: Profile, password, two-factor authentication, and passkey management. x-group: Profile & security - name: API keys description: Programmatic credentials. Creation and revocation are session-only. - name: Wallets description: Custodial and external (watch-only) wallets. - name: Balances description: Balance triples and lightweight gas reads. - name: Money movement description: | Faucet funding, minting, transfers, and redemptions. All four are asynchronous: the request is validated and recorded, the response is `201` with the transaction in status `QUEUED` (`txHash: null`), and a background worker executes it. Poll `GET /transactions/{id}` until `status` is `CONFIRMED`, `SETTLED`, or `FAILED`. Execution failures surface as status `FAILED` with `errorCode` on the transaction, never as an HTTP error on the POST. - name: Aro Mail description: >- Letters of value: escrow cAROUSD, print or mail through Lob, and let the recipient claim by QR or code. - name: Transactions description: >- History, single-transaction reads (pure database reads), and notarized receipts. - name: Sandbox description: Unauthenticated status and echo probes with a flat response shape. paths: /transfer/letter: post: tags: - Aro Mail summary: Create letter description: | Turn a private cAROUSD transfer into a mailable letter. Escrows `amount` from a **custodial** wallet into the Aro Mail vault (a `confidentialTransfer` to the platform operator) and returns the letter with its one-time `claimCode`, the `claimUrl` the QR encodes (`https:///claim#`, code in the URL fragment), and the `pdfUrl` of the printable page. Defaults depend on the destination: domestic letters (destination = the deployment's home country, `US` by default) are `visible` and expire in 90 days; international letters are `sealed` and expire in 45 days. Addresses follow the destination's rules (US: two-letter state, ZIP or ZIP+4, 64-character lines; elsewhere `region` or `postal` is required). Amounts above the per-letter cap return `400 invalid_amount`; too many letters in flight return `429 letter_velocity_limit`. Blocks up to ~20 s for the escrow receipt. A letter returned as `DRAFT` with a `PENDING` escrow leg becomes `ESCROWED` on a later read once the receipt lands **and** the encrypted amount is verified; a reverted or clamped escrow becomes `FAILED` with nothing moved. If the escrow was broadcast but the bookkeeping after it failed, the call returns `502 escrow_unsettled` instead of the letter: the letter exists as `DRAFT` (find it in `GET /transfer/letter`), value has left the wallet, and reconciliation finishes it on the next read. Do not create it again. `claimCode` and `claimUrl` are returned only here and on `GET /transfer/letter/{id}`, only to the owner, and only while the letter is not terminal. Anyone holding the code can claim once. operationId: createLetter requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateLetterRequest' example: walletId: ckwlt0001abcd amount: '50' recipient: name: Jane Doe address: line1: 12 Adeola Odeku Street line2: Victoria Island landmark: Opposite Eko Hotel city: Lagos region: LA country: NG memo: Thanks for the referral amountVisibility: sealed expiresInDays: 45 responses: '201': description: The letter, normally `ESCROWED` with a verified escrow leg. content: application/json: schema: $ref: '#/components/schemas/LetterEnvelope' example: ok: true data: letter: id: cklet0001abcd status: ESCROWED chainId: 11155111 amount: '50.00' token: cAROUSD amountVisibility: sealed memo: Thanks for the referral recipient: name: Jane Doe address: line1: 12 Adeola Odeku Street line2: Victoria Island landmark: Opposite Eko Hotel city: Lagos region: LA postal: null country: NG countryName: Nigeria isDomestic: false expiresAt: '2026-10-22T09:45:00.000Z' sender: walletId: ckwlt0001abcd address: '0x8Ba1f109551bD432803012645Ac136ddd64DBA72' claimCode: 7K3M-Q9TX-2ABF-H8RD-5CWN-VGP4-0J6Y claimUrl: >- https://dev.aropay.aro.media/claim#7K3M-Q9TX-2ABF-H8RD-5CWN-VGP4-0J6Y pdfUrl: >- https://dev.aropay.aro.media/api/v1/transfer/letter/cklet0001abcd/pdf escrow: transactionId: cktxn0005abcd txHash: 0x4d1e… explorerUrl: https://sepolia.etherscan.io/tx/0x4d1e… status: CONFIRMED verified: true claim: null refund: null mail: null needsReview: false error: null createdAt: '2026-09-07T09:45:00.000Z' updatedAt: '2026-09-07T09:45:31.000Z' '400': description: | Validation failure, invalid or unsupported destination address, amount above the per-letter cap, external wallet, or insufficient cAROUSD (`insufficient_confidential_balance`, also when the escrow transfer clamps to zero). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: ok: false error: code: invalid_postal_address message: >- US addresses need a two-letter state code and a ZIP or ZIP+4. '401': $ref: '#/components/responses/Unauthorized' '403': description: | Account disabled, or the recipient was blocked by screening (`recipient_blocked`, reserved for a future sanctions provider). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: ok: false error: code: account_disabled message: This account is disabled. '404': $ref: '#/components/responses/NotFound' '429': description: | Rate limit exceeded, or too many letters in flight for this sender or destination country (`letter_velocity_limit`). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: ok: false error: code: letter_velocity_limit message: >- Too many letters in flight. Try again once some are claimed, voided or expired. '500': $ref: '#/components/responses/InternalError' '502': description: | `transfer_failed`: the escrow transfer reverted on-chain; the letter is `FAILED` and nothing left the wallet. `escrow_unsettled`: the escrow transfer was broadcast (hash in `message`) but bookkeeping failed; the letter stays `DRAFT` with the tx hash on its escrow leg and is reconciled on its next read. Do not resubmit; list your letters and poll the draft. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: transfer_failed: summary: Escrow reverted; nothing moved value: ok: false error: code: transfer_failed message: Escrow transfer reverted on-chain. escrow_unsettled: summary: Escrow broadcast; bookkeeping pending value: ok: false error: code: escrow_unsettled message: >- The escrow transaction 0x5d2c… was submitted but could not be recorded fully; the letter will be reconciled on its next read. '503': description: | No public URL is configured on a production deployment (`public_url_not_configured`), or the confidential rail is unavailable. Platform-side. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: ok: false error: code: public_url_not_configured message: AROPAY_PUBLIC_URL is not configured. components: schemas: CreateLetterRequest: type: object required: - walletId - amount - recipient properties: walletId: type: string description: Sending wallet; must be custodial and hold enough cAROUSD. amount: type: string description: >- Decimal string in human units, up to the deployment's per-letter cap (default 10,000). examples: - '50' recipient: type: object required: - name - address properties: name: type: string minLength: 1 maxLength: 40 description: Printed on the letter and used as Lob's `to.name`. address: $ref: '#/components/schemas/LetterAddressInput' memo: type: string maxLength: 200 description: >- Optional note printed on the letter (hidden from the public preview for sealed letters). amountVisibility: type: string enum: - sealed - visible description: >- Defaults to `visible` for domestic letters and `sealed` for international ones. expiresInDays: type: integer minimum: 1 maximum: 180 description: >- Defaults to 90 (domestic) or 45 (international). Unclaimed letters refund the sender at expiry. LetterEnvelope: type: object required: - ok - data properties: ok: const: true data: type: object required: - letter properties: letter: $ref: '#/components/schemas/Letter' ErrorResponse: type: object description: The shared failure envelope. required: - ok - error properties: ok: const: false error: type: object required: - code - message properties: code: type: string description: Machine-readable error code; match on this, not `message`. message: type: string details: description: Structured context, e.g. per-field validation issues. LetterAddressInput: type: object description: | Recipient postal address as submitted. `country` is ISO 3166-1 alpha-2 (case-insensitive). Empty strings are treated as absent. Field lengths are Lob's verified input limits. required: - line1 - city - country properties: line1: type: string minLength: 1 maxLength: 200 description: Street line. At most 64 characters for US addresses. line2: type: string maxLength: 200 description: >- Optional second line (apartment, district). At most 64 characters for US addresses. landmark: type: string maxLength: 100 description: | Optional nearby landmark, printed as its own `Near …` line. It is folded into the second address line for Lob, so `line2 + landmark` must fit the destination's limit (64 US / 200 international). city: type: string minLength: 1 maxLength: 200 region: type: string maxLength: 200 description: | State, province or region. US: required two-letter state or territory code. Elsewhere: free text (ISO 3166-2 code or local name); either `region` or `postal` is required. postal: type: string maxLength: 40 description: | Postal code. US: required ZIP or ZIP+4. Elsewhere: optional when `region` is present. country: type: string minLength: 2 maxLength: 2 description: >- ISO 3166-1 alpha-2 country code, e.g. `NG`. Must not be on the deployment's block list. examples: - NG Letter: type: object description: | An Aro Mail letter: escrowed cAROUSD, a recipient address, a one-time claim code, and the legs that moved value. required: - id - status - chainId - amount - token - amountVisibility - memo - recipient - isDomestic - expiresAt - sender - claimCode - claimUrl - pdfUrl - escrow - claim - refund - mail - needsReview - error - createdAt - updatedAt properties: id: type: string examples: - cklet0001abcd status: type: string enum: - DRAFT - ESCROWED - MAILED - CLAIMING - CLAIMED - EXPIRED - VOIDED - FAILED description: | `DRAFT` (escrow submitted) → `ESCROWED` (escrow verified) → optional `MAILED` → `CLAIMING` → `CLAIMED`. `EXPIRED` and `VOIDED` carry a refund leg. `FAILED` means the escrow reverted, clamped or was never submitted: no value left the sender. Claimable: `ESCROWED`, `MAILED`. Terminal: `CLAIMED`, `EXPIRED`, `VOIDED`, `FAILED`. chainId: type: integer examples: - 11155111 amount: type: string description: >- Decimal string in human units. Cleartext to the parties; encrypted on-chain. token: type: string examples: - cAROUSD amountVisibility: type: string enum: - sealed - visible description: >- Whether the printed letter shows the amount. Defaults to `visible` domestic, `sealed` international. memo: type: - string - 'null' description: Up to 200 characters, printed on the letter. recipient: type: object required: - name - address properties: name: type: string address: $ref: '#/components/schemas/LetterAddress' isDomestic: type: boolean description: >- True when the destination is the deployment's home country (`US` by default). expiresAt: type: string format: date-time sender: type: object required: - walletId - address properties: walletId: type: - string - 'null' description: >- The sending wallet; `null` if that wallet was later deleted (refunds still go to `address`). address: type: string description: EIP-55 address the escrow came from and refunds return to. claimCode: type: - string - 'null' description: | Display form (`XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX`, 28 Crockford base32 symbols incl. two check symbols). Owner-only: present on create and single reads while the letter is non-terminal; `null` in lists and once terminal. claimUrl: type: - string - 'null' description: >- `https:///claim#`; the QR payload. Same visibility as `claimCode`. pdfUrl: type: string description: >- Absolute URL of `GET /transfer/letter/{id}/pdf`, built from the claim origin fixed at creation. escrow: description: >- The `LETTER_ESCROW` leg (sender → vault); `null` only if the row was never created. oneOf: - $ref: '#/components/schemas/LetterLeg' - type: 'null' claim: description: >- The `LETTER_CLAIM` leg (vault → recipient wallet); `null` until someone claims. oneOf: - allOf: - $ref: '#/components/schemas/LetterLeg' - type: object required: - claimedAt - walletAddress properties: claimedAt: type: - string - 'null' format: date-time description: Set when the letter reaches `CLAIMED`. walletAddress: type: - string - 'null' description: The wallet the value was released to. - type: 'null' refund: description: >- The `LETTER_REFUND` leg (vault → sender address); `null` unless the letter was voided or expired. oneOf: - allOf: - $ref: '#/components/schemas/LetterLeg' - type: object required: - reason properties: reason: type: string enum: - voided - expired - type: 'null' mail: description: >- Fulfilment details; `null` until `POST /transfer/letter/{id}/mail` is attempted. oneOf: - type: object required: - provider - providerId - deliveryMethod - status - trackingNumber - expectedDeliveryDate - mailedAt - testMode properties: provider: type: string examples: - lob providerId: type: - string - 'null' description: Lob letter id once accepted. deliveryMethod: type: - string - 'null' enum: - standard - tracked - courier - null status: type: - string - 'null' description: >- Lob letter status (`processed`, `rendered`, `failed`), refreshed on owner reads. trackingNumber: type: - string - 'null' description: >- USPS tracking number for `tracked` letters (dummy in test mode). expectedDeliveryDate: type: - string - 'null' description: Lob's estimate, `YYYY-MM-DD`. mailedAt: type: - string - 'null' format: date-time testMode: type: boolean description: >- True when the deployment uses a Lob test key; nothing is printed or mailed. - type: 'null' needsReview: type: boolean description: >- True when a leg could not be verified automatically; nothing moves until an operator reviews `error`. error: type: - string - 'null' description: Failure or review context for the most recent leg. createdAt: type: string format: date-time updatedAt: type: string format: date-time LetterAddress: type: object description: Recipient postal address as stored, with the resolved country name. required: - line1 - line2 - landmark - city - region - postal - country - countryName properties: line1: type: string line2: type: - string - 'null' landmark: type: - string - 'null' description: Printed as `Near …` on the letter. city: type: string region: type: - string - 'null' postal: type: - string - 'null' country: type: string description: ISO 3166-1 alpha-2, upper-case. examples: - NG countryName: type: string examples: - Nigeria LetterLeg: type: object description: >- One on-chain leg of a letter (escrow, release or refund), linked to its transaction row. required: - transactionId - txHash - explorerUrl - status - verified properties: transactionId: type: string description: The `Transaction` id; read it with `GET /transactions/{id}`. examples: - cktxn0005abcd txHash: type: - string - 'null' explorerUrl: type: - string - 'null' status: type: string enum: - PENDING - CONFIRMED - SETTLING - SETTLED - FAILED description: The linked transaction's status. verified: type: boolean description: | True once the leg's `ConfidentialTransfer` event was decrypted and matched the letter amount. The letter only changes status after verification, so `CONFIRMED` + `verified: false` means the receipt is in and verification is pending. responses: Unauthorized: description: Missing or invalid credential. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: ok: false error: code: invalid_api_key message: Invalid API key. NotFound: description: Resource not found within this account. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: ok: false error: code: not_found message: Resource not found. InternalError: description: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: ok: false error: code: internal_error message: An unexpected error occurred. securitySchemes: apiKeyAuth: type: http scheme: bearer bearerFormat: aro_sk_… description: | AroPay API key, sent as `Authorization: Bearer aro_sk_…`. Created in the dashboard under Settings → API keys. Takes precedence over a session cookie when both are present. x-default: aro_sk_your_key_here sessionCookie: type: apiKey in: cookie name: aropay_session description: | Browser session cookie minted by `POST /auth/login` (or passkey login). httpOnly, `SameSite=Lax`, 24 h TTL. Endpoints marked **Session-only** accept only this credential and return `403 session_required` for API keys. ````