> ## 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.

# 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.

<Columns cols={2}>
  <Card title="Custodial" icon="building-columns" iconType="duotone">
    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.
  </Card>

  <Card title="External" icon="binoculars" iconType="duotone">
    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.
  </Card>
</Columns>

## 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`      |     ✓     |           ✓          |

<Note>
  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.
</Note>

## Creating wallets

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

<CodeGroup>
  ```bash Custodial theme={null}
  curl -s "$BASE/wallets" \
    -H "Authorization: Bearer $KEY" \
    -H "content-type: application/json" \
    -d '{"type":"custodial","label":"Payouts"}'
  ```

  ```bash External (raw address) theme={null}
  curl -s "$BASE/wallets" \
    -H "Authorization: Bearer $KEY" \
    -H "content-type: application/json" \
    -d '{"type":"external","address":"0x8Ba1f109551bD432803012645Ac136ddd64DBA72","label":"Ops multisig"}'
  ```

  ```bash External (.nota address card) theme={null}
  curl -s "$BASE/wallets" \
    -H "Authorization: Bearer $KEY" \
    -H "content-type: application/json" \
    -d "{\"type\":\"external\",\"nota\":\"$(cat address-card.nota)\",\"label\":\"Counterparty\"}"
  ```
</CodeGroup>

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

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

`GET /wallets/{id}` additionally returns live [balances](/concepts/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](/guides/export-and-backup), 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](/concepts/nota-files).