# Wallet setup

> Prepare your AGARA deposit wallet before funding it or trading through the API.

Each account has an AGARA deposit wallet on Base. Complete wallet
setup in the web app before funding it or submitting orders.

## Set up your wallet [#set-up-your-wallet]

1. Sign in at `https://app.agara.xyz` with the identity you will use for the account.
2. Open **Settings**, then complete the AGARA wallet setup.
3. Wait until the app reports that the wallet is ready.
4. Create a personal access token with only the scopes your trading
   application needs. See [Authentication](/docs/authentication).

Wallet registration and setup require a current browser session. A personal
access token cannot create or configure a wallet.

## Browser-session endpoints [#browser-session-endpoints]

The web app uses these endpoints during setup:

| Method | Path                        | Purpose                                       |
| ------ | --------------------------- | --------------------------------------------- |
| `POST` | `/trade/v1/wallet/register` | Register the signed-in account for AGARA      |
| `POST` | `/trade/v1/wallet/setup`    | Deploy and configure the AGARA deposit wallet |
| `GET`  | `/trade/v1/wallet/status`   | Read the current setup state                  |

Send the current Privy identity token as a bearer token. These endpoints do
not accept personal access tokens.

## When setup does not succeed [#when-setup-does-not-succeed]

Setup continues after the request returns, so a failure is reported rather than
raised as an error response. `POST /trade/v1/wallet/setup` can report one in the
entry it accepts, and `GET /trade/v1/wallet/status` reports one that happened
later. Both carry a `failure` object in the same shape as every other
[error](/docs/errors): a stable `code`, display text, and a `recovery`
instruction.

Read `failure.code`. These are the terminal codes setup can report:

| Terminal code                  | Action                                                                                                                                                                                                |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `wallet_setup_failed`          | Setup did not complete. Start it again from **Settings**, and if the wallet already reports as configured, read the status again before retrying                                                      |
| `chain_execution_failed`       | The setup transaction reverted on-chain. Start setup again from **Settings**                                                                                                                          |
| `internal_error`               | Retain the account identifier and the request ID, then contact support                                                                                                                                |
| `wallet_setup_outcome_unknown` | Do not start setup again, and do not send funds. Whether the wallet was created is genuinely uncertain, and a second attempt can strand collateral. Retain the account identifier and contact support |

While setup is paused for maintenance, `POST /trade/v1/wallet/setup` answers
the AGARA entry `FAILED` with `account_operations_paused`, and
`GET /trade/v1/wallet/status` shows the wallet as not yet set up. Start setup
again in a few minutes.

Treat `wallet_setup_outcome_unknown` as unresolved until support confirms the
outcome. Wait for a ready wallet before funding it or creating a personal access
token.

## Fund the ready wallet [#fund-the-ready-wallet]

Send only `USDC` at [`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`](https://basescan.org/address/0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913) on Base to
the deposit-wallet address shown in Settings. See [Collateral](/docs/tokens/collateral)
before moving funds.

After funding, wait for `cash_balance_micro` in
[`GET /trade/v1/portfolio/summary`](/docs/portfolio#summary) to reflect the
deposit before placing orders.