Developer Docs

Authentication

All endpoints require the following headers unless otherwise noted:

string

required

Bearer token (JWT) for end-user authentication. Format: Bearer YOUR_JWT_TOKEN

string

required

Your Magic secret key for application-level authentication.

Create or Fetch Account

Create a new account or return the existing one for the authenticated user. Wallet addresses are provisioned for supported EVM and Solana chains.

cURL

curl -X POST 'https://uoa-server.magic.xyz/account' \
  -H 'Authorization: Bearer USER_JWT_TOKEN' \
  -H 'X-MAGIC-SECRET-KEY: YOUR_MAGIC_SECRET_KEY'

Response: New accounts include a default perp_dex_status entry for every supported venue (lowercase keys: extended, hyperliquid, paradex, nado, polymarket). Each value is a JSON object; at minimum venues expose initialized (boolean) and may add venue-specific fields (addresses, keys, trade_initialized, etc.) as onboarding progresses.

{
  "success": true,
  "app_user_id": "user-123",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "public_address": {
    "ETH": "0x1234567890abcdef1234567890abcdef12345678",
    "SOL": "7nYB5F2xVT9hVjhxUoZ5HQxvPz2kTmSoQvGPmxfTjKN"
  },
  "perp_dex_status": {
    "extended": {
      "initialized": false,
      "account_id": null,
      "vault": null,
      "stark_public_key": null,
      "api_key": null
    },
    "hyperliquid": { "initialized": false, "account_address": null },
    "paradex": {
      "initialized": false,
      "l2_address": null,
      "l2_public_key": null
    },
    "nado": { "initialized": false, "account_address": null },
    "polymarket": {
      "initialized": false,
      "proxy_wallet_address": null,
      "magic_wallet_address": null
    }
  }
}

Response Fields

boolean

Whether the account was created or fetched successfully.

string

The user identifier from your application (JWT sub claim).

string

The UOA-internal user UUID.

object

Map of chain code to wallet address. Provisioning creates ETH (EVM) and SOL entries; the same EVM address is used for Arbitrum, Polygon, Ink, and Ethereum when resolving balances or transfers server-side.

object

Map of perp venue to stored status (keys match venue ids: extended, hyperliquid, paradex, nado, polymarket). Shape is venue-specific; see the default example above for fields present on create.

Get Account Info

Return the authenticated user’s stored account state.

cURL

curl -X GET 'https://uoa-server.magic.xyz/account' \
  -H 'Authorization: Bearer USER_JWT_TOKEN' \
  -H 'X-MAGIC-SECRET-KEY: YOUR_MAGIC_SECRET_KEY'

Response: Same top-level fields as create, except there is no success field. perp_dex_status always includes all venue keys; initialized venues gain non-null fields (e.g. Hyperliquid account_address, trade_initialized when applicable).

{
  "app_user_id": "user-123",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "public_address": {
    "ETH": "0x1234567890abcdef1234567890abcdef12345678",
    "SOL": "7nYB5F2xVT9hVjhxUoZ5HQxvPz2kTmSoQvGPmxfTjKN"
  },
  "perp_dex_status": {
    "extended": { "initialized": false, "account_id": null },
    "hyperliquid": {
      "initialized": true,
      "account_address": "0x1234567890abcdef1234567890abcdef12345678"
    },
    "paradex": { "initialized": false, "l2_address": null },
    "nado": { "initialized": false, "account_address": null },
    "polymarket": { "initialized": false, "proxy_wallet_address": null }
  }
}

Response Fields

string

The user identifier from your application.

string

The UOA-internal user UUID.

object

Map of chain code to wallet address (typically ETH and SOL as stored keys).

object

Map of venue id to JSON status for that venue (extended, hyperliquid, paradex, nado, polymarket). Exact keys per venue evolve with the product; treat as opaque except for documented init flows.

Demo: Get Wallet Balance

Get on-chain wallet balances for one chain. This endpoint is for demo usage only.

cURL

curl -X GET 'https://uoa-server.magic.xyz/demo/wallet/balance?chain=ARB' \
  -H 'Authorization: Bearer USER_JWT_TOKEN' \
  -H 'X-MAGIC-SECRET-KEY: YOUR_MAGIC_SECRET_KEY'

Do not use this endpoint as a production asset API. For production apps, use the EVM and Solana wallet addresses from public_address and fetch balances with your own RPC provider.

Response:

{
  "chain": "ARB",
  "address": "0x1234...5678",
  "assets": {
    "ETH": "0.01",
    "USDC": "250.00"
  },
  "public_address": {
    "ETH": "0x1234...5678",
    "SOL": "7nYB5F...TjKN"
  }
}

Query Parameters

string

required

The chain to fetch balances for. Values: ETH, ARB, POL, INK, SOL

Response Fields

string

The requested chain.

string | null

The wallet address used for the balance query (EVM chains use the stored ETH address; Solana uses the SOL address). May be null if no address exists for the requested chain.

object

Map of token codes to decimal string balances for the requested chain.

object

Map of chain code to wallet address.

Unified Orchestration Accounts

API Reference

Accounts

Authentication

Create or Fetch Account

Response Fields

Get Account Info

Response Fields

Demo: Get Wallet Balance

Query Parameters

Response Fields

​Authentication

​Create or Fetch Account

​Response Fields

​Get Account Info

​Response Fields

​Demo: Get Wallet Balance

​Query Parameters

​Response Fields

Authentication

Create or Fetch Account

Response Fields

Get Account Info

Response Fields

Demo: Get Wallet Balance

Query Parameters

Response Fields