---
title: Wallet Overview
description: The managed wallet behind your account.
---

Every account gets a **Superior-managed trading wallet** on first use - the live credential source for [deployments](/runtime/credentials) and typed [one-time venue executions](/runtime/executions). It lives in Privy's secured wallet infrastructure under Superior's platform controls (the same custody that runs the [Terminal](https://terminal.superior.trade)); you never handle a key. Prefer full self-custody? [BYOK](/runtime/credentials) is coming soon.

### GET /wallet

The wallet, its balance, and how to fund it:

```json
{
  "address": "0x3a8d91d1...",
  "deposit": {
    "chain": "arbitrum",
    "asset": "USDC",
    "address": "0x3a8d91d1...",
    "min_usd": 50,
    "protocol_min_usd": 5
  },
  "balance": {
    "held_usd": 205.4,
    "networks": [
      {
        "network": "arbitrum",
        "address": "0x3a8d91d1...",
        "asset": "USDC",
        "balance": 180.4,
        "balance_usd": 180.4
      },
      {
        "network": "polygon",
        "address": "0x3a8d91d1...",
        "asset": "USDC",
        "balance": 25,
        "balance_usd": 25
      }
    ],
    "allocated": [
      {
        "venue": "hyperliquid",
        "deployment": "dep_01j8xv...",
        "balance_usd": 141.2
      },
      {
        "venue": "polymarket",
        "deployment": "dep_01k2pm...",
        "balance_usd": 75
      },
      { "venue": "lighter", "deployment": "dep_01k2lt...", "balance_usd": 45 }
    ],
    "total_usd": 466.6
  }
}
```

`min_usd` is Superior's customer-facing minimum. `protocol_min_usd` is
Hyperliquid's lower bridge safety floor; it is not the recommended deposit
amount.

- `networks` — USDC still held on-chain. Arbitrum and Polygon are always present, including at zero, and `address` identifies the wallet queried on that network.
- `held_usd` — the sum of `networks[].balance_usd` ([deposit](/wallet/deposits) to grow it).
- `allocated` — one balance for each onboarded venue. Hyperliquid, Polymarket, and Lighter are omitted until onboarded, but remain present with `balance_usd: 0` after onboarding.
- `total_usd` — `held_usd` plus every returned venue balance, with each location counted once.

Allocated venue entries intentionally do not expose venue account addresses. `deployment` appears only when exactly one non-deleted deployment uses that venue account; it is omitted when no deployment or multiple deployments share the balance.

Balance reads are all-or-nothing. If either network or any onboarded venue cannot be read, `GET /wallet` returns `502` and never returns a partial total.

## Lifecycle

1. **[Deposit](/wallet/deposits)** USDC on Arbitrum → appears in the Arbitrum network row and contributes to `held_usd` on arrival. USDC held by the same address on Polygon appears in the Polygon row.
2. **Set up a venue** with `POST /wallet/venues/{venue}/setup` and any authenticated API key. This is the explicit authorization to allocate at least $50.00 from `held_usd`; poll `GET /wallet` for progress.
3. **Deploy or execute** only after that venue is `ready`. A one-time execution never starts setup or moves funds implicitly.
4. **Stop / delete**: infrastructure never market-closes positions; deleting a deployment leaves its funds on the venue account, still yours and still counted in `allocated`.
5. **[Withdraw](/wallet/withdrawals)** from an explicit source. `source=arbitrum` uses `held_usd`; `source=hyperliquid` uses only `perp_withdrawable_usd`. Balances are never combined and sources never fall back.

## How it relates to credentials

`{ "credentials": { "type": "managed" } }` on a deployment (the default — omission means the same) uses the account-level managed wallet. Managed live Freqtrade is the exception to manual setup: it explicitly authorizes its configured `available_capital` through the durable deployment venue-setup operation. Paper and BYOK do not allocate managed capital; managed live Nautilus remains unavailable without its own capital authorization contract. The [credentials page](/runtime/credentials) covers the managed-wallet path and planned BYOK path.

## Venue readiness and explicit setup

`GET /wallet` also returns exactly three venue summaries: `hyperliquid`, `polymarket`, and `lighter`. Each includes its `$50.00` `minimum_deposit_usd`, venue `balance_usd`, safe deposit destination when known, readiness checks, and only that venue's latest safe operation summary. A check can be `true`, `false`, or `"unknown"`; `unknown` is not a negative readiness result.

When a venue balance cannot be read, its `balance_usd` is `null`, never zero. The same poll still exposes the affected venue's latest safe operation summary, so use `GET /wallet` to continue tracking setup without a separate venue or operation read route.

Use the sole venue-funding mutation with any authenticated API key and a required `Idempotency-Key`:

```http
POST /wallet/venues/{venue}/setup
```

```json
{ "amount_usd": "50.00" }
```

`amount_usd` is a canonical positive decimal string with at most six fractional digits. `$50.00` is the hard minimum for every venue. The request reserves from `held_usd`; it cannot use a third-party source wallet. A same-key/same-request replay is safe, while a changed request returns `409 idempotency_key_conflict`. An active different setup for the same venue returns `409 venue_setup_in_progress`.

The response is `201` when the operation finishes within the request budget or `202` while work remains. Do not look for a venue or operation GET endpoint: poll `GET /wallet`. It exposes only `id`, `status`, `step`, `updated_at`, and a sanitized error for the latest operation.

The public setup contract and MCP tool `wallet.venue.setup` are available, and production provider runtime is wired for the enabled rollout. `FEATURE_UNIFIED_VENUE_WALLET_SETUP` and required runtime dependencies still gate availability; when either is unavailable, setup and managed deployment funding fail closed without moving funds. Managed live Nautilus deployment-capital automation remains unavailable until it has an explicit capital authorization contract.

If the provider cannot prove the setup outcome before its reconciliation deadline, the operation becomes `reconciliation_required`. Automatic retries stop, the reserved balance remains held against that operation, and an operator must reconcile the venue outcome before another allocation is attempted.