Wallets

Custodial and external wallets: what each can do, how keys are protected, and the rules that apply to both.

Every AroPay account can hold up to 10 wallets of two kinds. The first wallet you create becomes the account’s primary wallet.

Custodial

An EOA generated server-side. The sandbox holds the private key (AES-256-GCM encrypted at rest) and signs on your behalf, so API keys can mint, transfer, and redeem without any client-side signing.

External

A watch-only address you register: paste a raw address or import a Notareum address card (.nota file). It can receive funds and be monitored, but never spend through the sandbox.

Capability matrix

Capability	Custodial	External
Receive stablecoin / cAROUSD	✓	✓
View public + gas balances	✓	✓
View decrypted confidential balance	✓	No (shown encrypted)
Fund from faucet	✓	✓
Mint / transfer / redeem	✓	No
Export key as encrypted .nota	✓	No
Shareable address card .nota	✓	✓

Spending endpoints (/mint, /transfer, /redeem) reject external wallets with a 400; the sandbox has no key to sign with. External wallets are for receiving and observing.

Creating wallets

Create a custodial wallet, or register an external one by address or by importing an address card:

Custodial

curl -s "$BASE/wallets" \
  -H "Authorization: Bearer $KEY" \
  -H "content-type: application/json" \
  -d '{"type":"custodial","label":"Payouts"}'

For external wallets, pass either address or nota, never both. Addresses are validated and stored EIP-55 checksummed; registering an address that already exists in the sandbox returns 409 wallet_exists.

The wallet object

{
  "id": "ckwlt0001…",
  "address": "0x8Ba1f109551bD432803012645Ac136ddd64DBA72",
  "type": "CUSTODIAL",
  "label": "Payouts",
  "isPrimary": true,
  "createdAt": "2026-08-13T09:30:00.000Z"
}

GET /wallets/{id} additionally returns live balances alongside the wallet.

How custodial keys are protected

• Private keys are generated server-side and never returned by any endpoint, logged, or exposed to the dashboard.
• At rest they are AES-256-GCM encrypted with a per-wallet IV and authentication tag under a platform master key.
• Keys are decrypted only transiently, in memory, to sign a transaction.
• The only way key material leaves the platform is a deliberate, session-only export, and even then it is re-encrypted under a passphrase you choose before it is returned.

Address cards

Any wallet can produce a shareable address card: a .nota file carrying the public address and chain context (no key material). It’s the file twin of a receive QR code: counterparties import it into any Aro recipient field instead of copy-pasting a hex string. See .nota files.