Wallet Overview

The managed wallet behind your account.

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

GET/wallet#

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

{
  "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 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 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 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 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:

POST /wallet/venues/{venue}/setup

{ "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.