# AroPay

> AroPay: sealed, private payments on public ledgers, built on the Aro Confidential Rails with Zama Protocol FHE. Currently an MVP sandbox for B2B users.

## Docs

- [Welcome to AroPay](https://docs.aropay.aro.media/index.md): AroPay is a confidential payments solution for sending sealed, private payments on public ledgers without exposing confidential information, built on the Aro Confidential Rails with Zama Protocol FHE.
- [Quickstart](https://docs.aropay.aro.media/quickstart.md): Go from a fresh AroPay account to your first confidential transfer in about five minutes.
- [How AroPay works](https://docs.aropay.aro.media/concepts/how-aropay-works.md): The architecture of the AroPay sandbox: accounts, wallets, the two money rails, the operator, and mint modes.
- [Wallets](https://docs.aropay.aro.media/concepts/wallets.md): Custodial and external wallets: what each can do, how keys are protected, and the rules that apply to both.
- [Balances](https://docs.aropay.aro.media/concepts/balances.md): The balance triple (normal, confidential, total) plus per-wallet gas, and how decryption works for each wallet type.
- [Confidential transfers](https://docs.aropay.aro.media/concepts/confidential-transfers.md): How cAROUSD keeps amounts private on a public chain: ERC-7984, fully homomorphic encryption, and what observers can and cannot see.
- [Transactions](https://docs.aropay.aro.media/concepts/transactions.md): The transaction object, its lifecycle from PENDING to terminal states, and how lazy reconciliation keeps statuses current.
- [.nota files](https://docs.aropay.aro.media/concepts/nota-files.md): Notareum resource files: shareable address cards, passphrase-encrypted key exports, and notarized transaction receipts.
- [Fund a wallet](https://docs.aropay.aro.media/guides/fund-a-wallet.md): Get test stablecoin and gas into a wallet: from the faucet, from a counterparty, or by receiving on-chain.
- [Mint cAROUSD](https://docs.aropay.aro.media/guides/mint-carousd.md): Convert public test stablecoin into encrypted cAROUSD and step onto the confidential rail.
- [Send transfers](https://docs.aropay.aro.media/guides/send-transfers.md): Move value publicly or privately with one endpoint: standard ERC-20 transfers and FHE-encrypted confidential transfers.
- [Redeem cAROUSD](https://docs.aropay.aro.media/guides/redeem-carousd.md): Burn confidential funds and receive public stablecoin 1:1, with asynchronous settlement you can track.
- [Track transactions](https://docs.aropay.aro.media/guides/track-transactions.md): List, filter, and poll transactions; link out to the explorer; and download notarized receipts.
- [Export & backup](https://docs.aropay.aro.media/guides/export-and-backup.md): Take a custodial wallet's key with you as a passphrase-encrypted .nota file, and share addresses safely with address cards.
- [Authentication](https://docs.aropay.aro.media/security/authentication.md): Two interchangeable credentials (browser sessions and API keys), plus the rules for which endpoints accept which.
- [API keys](https://docs.aropay.aro.media/security/api-keys.md): Create, use, rotate, and revoke aro_sk_ keys: limits, expiry, and how keys are stored.
- [Two-factor authentication](https://docs.aropay.aro.media/security/two-factor-authentication.md): TOTP enrollment, the two-step login flow, and recovery: RFC 6238 codes with single-use replay protection.
- [Passkeys](https://docs.aropay.aro.media/security/passkeys.md): Phishing-resistant, passwordless sign-in with WebAuthn: registration, usernameless login, and device management.
- [Rate limits](https://docs.aropay.aro.media/security/rate-limits.md): Per-principal read/write budgets, login throttles, lockout rules, and how to handle 429s.
- [Security model](https://docs.aropay.aro.media/security/security-model.md): How AroPay protects credentials, keys, and funds: a summary of the platform's security architecture.
- [Troubleshooting](https://docs.aropay.aro.media/support/troubleshooting.md): Symptom-to-cause table for the errors you're most likely to hit, and what to do about each.
- [API introduction](https://docs.aropay.aro.media/api-reference/introduction.md): Base URL, authentication, the response envelope, conventions, and everything global to the AroPay API v1.
- [Errors](https://docs.aropay.aro.media/api-reference/errors.md): The error envelope and the complete catalog of error codes, grouped by HTTP status.
- [Log in](https://docs.aropay.aro.media/api-reference/auth/log-in.md): Authenticate with email and password. On success the response sets the `aropay_session` cookie (httpOnly, `SameSite=Lax`, 24 h TTL) and returns the user.
- [Complete TOTP login](https://docs.aropay.aro.media/api-reference/auth/complete-totp-login.md): Second step for accounts with two-factor authentication. Exchange the `pendingToken` from `POST /auth/login` plus a live 6-digit authenticator code for a session. Codes are single-use within their 30-second window.
- [Get passkey login options](https://docs.aropay.aro.media/api-reference/auth/get-passkey-login-options.md): Produce WebAuthn authentication options. Include `email` to scope the challenge to one account, or omit it for usernameless login with discoverable credentials. The challenge is bound to the client via a signed, short-lived cookie that must accompany the subsequent `POST /auth/passkey/verify`.
- [Verify passkey login](https://docs.aropay.aro.media/api-reference/auth/verify-passkey-login.md): Verify the WebAuthn assertion produced by the authenticator and mint a session. Requires the challenge cookie set by `POST /auth/passkey/options`. A passkey login counts as strong MFA on its own; no TOTP step follows.
- [Get session](https://docs.aropay.aro.media/api-reference/auth/get-session.md): Return the authenticated principal and which credential authenticated it. Works with either an API key or a session cookie, a convenient first call to verify integration credentials.
- [Log out](https://docs.aropay.aro.media/api-reference/auth/log-out.md): Clear the session cookie. Safe to call regardless of state.
- [Get profile](https://docs.aropay.aro.media/api-reference/profile-&-security/get-profile.md): Return the authenticated account's profile.
- [Update profile](https://docs.aropay.aro.media/api-reference/profile-&-security/update-profile.md): Update `name` and/or `company`. At least one field is required.
- [Change password](https://docs.aropay.aro.media/api-reference/profile-&-security/change-password.md): **Session-only.** Change the account password. Policy: 10–200 characters including an uppercase letter, a lowercase letter, and a digit. Success bumps the account's token version (every other session is invalidated) and refreshes the current session cookie.
- [Set up TOTP](https://docs.aropay.aro.media/api-reference/profile-&-security/set-up-totp.md): **Session-only.** Begin two-factor enrollment. Returns the base32 secret, an `otpauth://` URI, and a QR data URL to scan. Enforcement does not start until `POST /me/totp/enable` confirms a live code.
- [Enable TOTP](https://docs.aropay.aro.media/api-reference/profile-&-security/enable-totp.md): **Session-only.** Confirm enrollment with a live 6-digit code from the authenticator. Two-factor enforcement starts when this succeeds.
- [Disable TOTP](https://docs.aropay.aro.media/api-reference/profile-&-security/disable-totp.md): **Session-only.** Turn off two-factor authentication. Requires both the account password and a live code; an unlocked session alone is not sufficient.
- [List passkeys](https://docs.aropay.aro.media/api-reference/profile-&-security/list-passkeys.md): List the account's registered WebAuthn credentials.
- [Get passkey registration options](https://docs.aropay.aro.media/api-reference/profile-&-security/get-passkey-registration-options.md): **Session-only.** Produce WebAuthn registration options for adding a passkey to the current account. The challenge rides in a signed cookie bound to the account and must accompany `POST /me/passkeys/register`.
- [Register passkey](https://docs.aropay.aro.media/api-reference/profile-&-security/register-passkey.md): **Session-only.** Verify the authenticator's attestation against the challenge cookie and store the credential. Optionally name the device.
- [Delete passkey](https://docs.aropay.aro.media/api-reference/profile-&-security/delete-passkey.md): **Session-only.** Remove a registered passkey from the account.
- [List API keys](https://docs.aropay.aro.media/api-reference/api-keys/list-api-keys.md): List the account's API keys: prefix and metadata only. The full secret is never retrievable after creation.
- [Create API key](https://docs.aropay.aro.media/api-reference/api-keys/create-api-key.md): **Session-only.** Create a key. The response's `plaintext` (the full `aro_sk_…` secret) is shown exactly once; only its SHA-256 hash is stored. Accounts can hold at most 10 active keys.
- [Revoke API key](https://docs.aropay.aro.media/api-reference/api-keys/revoke-api-key.md): **Session-only.** Revoke a key immediately. Idempotent: revoking an already-revoked key returns the same success.
- [List wallets](https://docs.aropay.aro.media/api-reference/wallets/list-wallets.md): List all wallets on the account.
- [Create wallet](https://docs.aropay.aro.media/api-reference/wallets/create-wallet.md): Create a custodial wallet (server-generated EOA, key encrypted at rest) or register an external watch-only address. For external wallets pass **either** `address` **or** `nota` (a Notareum address card), never both. Accounts can hold at most 10 wallets; the first becomes primary.
- [Get wallet](https://docs.aropay.aro.media/api-reference/wallets/get-wallet.md): Return one wallet together with its live balance triple.
- [Get address card](https://docs.aropay.aro.media/api-reference/wallets/get-address-card.md): Produce a shareable Notareum **address card**: the file twin of a receive QR. Contains the public address and chain context only, no key material. Counterparties import it into any Aro recipient field.
- [Export wallet key](https://docs.aropay.aro.media/api-reference/wallets/export-wallet-key.md): **Session-only.** Export a custodial wallet's private key as a passphrase-encrypted `.nota` envelope (PBKDF2-SHA256 with 310,000 iterations + AES-256-GCM, applied server-side; the plaintext key never leaves the platform). Only custodial wallets can be exported.
- [Get balances](https://docs.aropay.aro.media/api-reference/balances/get-balances.md): Return the balance triple of `normal` (public stablecoin), `confidential` (cAROUSD; decrypted server-side for custodial wallets), and `total`, plus gas ETH, for every wallet or one wallet.
- [Get gas balances](https://docs.aropay.aro.media/api-reference/balances/get-gas-balances.md): Lightweight per-wallet ETH (gas) balances plus the account total. Plain balance reads only (no token or FHE work), so this endpoint is **safe to poll**; it backs the dashboard's gas indicator. A wallet whose RPC read fails reports zero rather than failing the request.
- [Fund wallet](https://docs.aropay.aro.media/api-reference/money-movement/fund-wallet.md): Faucet: the platform operator sends test stablecoin to the wallet and tops up Sepolia ETH for gas in the same call. `amount` is optional; omit it for the deployment default. Faucet volume is capped per account over a rolling 24 hours.
- [Mint cAROUSD](https://docs.aropay.aro.media/api-reference/money-movement/mint-carousd.md): Convert public test stablecoin into encrypted cAROUSD at 1:1. Requires a **custodial** wallet. In backed mode the wallet deposits stablecoin into the commitment contract; in float mode the operator mints directly. Amount encryption happens server-side.
- [Transfer funds](https://docs.aropay.aro.media/api-reference/money-movement/transfer-funds.md): Send from a **custodial** wallet on either rail: `type: "public"` is a standard ERC-20 stablecoin transfer; `type: "private"` is a cAROUSD `confidentialTransfer` whose amount is FHE-encrypted on-chain.
- [Redeem cAROUSD](https://docs.aropay.aro.media/api-reference/money-movement/redeem-carousd.md): Burn cAROUSD from a **custodial** wallet and receive public test stablecoin 1:1. Settlement is asynchronous: the transaction moves `PENDING → SETTLING → SETTLED`, with the payout hash in `settlementTxHash`. Settlement advances lazily when the transaction is read; poll `GET /transactions/{id}` until…
- [List transactions](https://docs.aropay.aro.media/api-reference/transactions/list-transactions.md): Paginated transaction history, newest first. In-flight rows are lazily reconciled on read.
- [Get transaction](https://docs.aropay.aro.media/api-reference/transactions/get-transaction.md): Return one transaction. Reading a non-terminal transaction triggers reconciliation (receipt lookups and redeem settlement), so polling this endpoint is what drives in-flight rows to completion. Poll until `status` is `CONFIRMED`, `SETTLED`, or `FAILED`.
- [Get transaction receipt](https://docs.aropay.aro.media/api-reference/transactions/get-transaction-receipt.md): Produce a notarized Notareum receipt (`.nota` file) for a transaction that reached the chain. Returns `400` while the transaction cannot yet be represented (e.g. no hash yet); retry after it confirms.
- [Get sandbox status](https://docs.aropay.aro.media/api-reference/sandbox/get-sandbox-status.md): Unauthenticated service probe with a **flat** response shape (no `data` envelope). Use it to verify connectivity.
- [Echo JSON](https://docs.aropay.aro.media/api-reference/sandbox/echo-json.md): Unauthenticated echo probe with a **flat** response shape. Send any valid JSON and receive it back under `echo`, useful for verifying JSON serialization end to end. Invalid JSON returns a flat `400 { "ok": false, "error": "<string>" }`.

## OpenAPI Specs

- [openapi](https://docs.aropay.aro.media/api-reference/openapi.yaml)