Skip to main content

​
Authentication

All endpoints require the following headers unless otherwise noted:
​
Authorization
string
required
Bearer token (JWT) for end-user authentication. Format: Bearer YOUR_JWT_TOKEN
​
X-MAGIC-SECRET-KEY
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. Wallets are provisioned across all supported chains automatically.
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: 
{
  "success": true,
  "app_user_id": "user-123",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "public_address": {
    "ETH": "0x1234567890abcdef1234567890abcdef12345678",
    "SOL": "7nYB5F2xVT9hVjhxUoZ5HQxvPz2kTmSoQvGPmxfTjKN"
  },
  "perp_dex_status": {}
}

​
Response Fields

​
success
boolean
Whether the account was created or fetched successfully.
​
app_user_id
string
The user identifier from your application (JWT sub claim).
​
user_id
string
The UOA-internal user UUID.
​
public_address
object
Map of chain code to wallet address (e.g., {"ETH": "0x...", "SOL": "7nYB..."}).
​
perp_dex_status
object
Map of DEX venue to initialization status.

​
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: 
{
  "app_user_id": "user-123",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "public_address": {
    "ETH": "0x1234...5678",
    "ARB": "0x1234...5678",
    "SOL": "7nYB5F...TjKN"
  },
  "perp_dex_status": {
    "hyperliquid": { "initialized": true }
  }
}

​
Response Fields

​
app_user_id
string
The user identifier from your application.
​
user_id
string
The UOA-internal user UUID.
​
public_address
object
Map of chain code to wallet address.
​
perp_dex_status
object
Map of DEX venue to initialization status.

​
Get Wallet Balances

Get on-chain wallet balances for the authenticated user across all chains.
cURL
curl -X GET 'https://uoa-server.magic.xyz/account/wallet' \
  -H 'Authorization: Bearer USER_JWT_TOKEN' \
  -H 'X-MAGIC-SECRET-KEY: YOUR_MAGIC_SECRET_KEY'
Response: 
{
  "public_address": {
    "ETH": "0x1234...5678",
    "ARB": "0x1234...5678"
  },
  "assets": {
    "ETH": { "ETH": "0.05", "USDC": "100.00" },
    "ARB": { "ETH": "0.01", "USDC": "250.00" }
  }
}

​
Response Fields

​
public_address
object
Map of chain code to wallet address.
​
assets
object
Map of chain code to token balances. Each chain maps token codes to decimal string amounts.