Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.magic.link/llms.txt

Use this file to discover all available pages before exploring further.

​
Prerequisites

Before using UOA, you need:
1

Create a Magic Account

Visit the Magic Dashboard and sign up for a Magic developer account.
2

Get your API keys

In your dashboard, create a new application and obtain your Secret Key. You will use this as the X-MAGIC-SECRET-KEY header on all requests.
3

Set up authentication

Configure your application to issue JWTs for end users.
4

Set up Server Wallets

Follow the dashboard guide to set up Server Wallets for your application. Use the same Magic credential and returned provider ID when registering your UOA wallet setup.
5

Register your app with UOA

Register your application with your Magic secret key and OIDC configuration so UOA can validate your user JWTs.
cURL
curl -X POST 'https://uoa-server.magic.xyz/apps' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "My App",
    "magic_app_secret_key": "sk-live-XXXXXXXX",
    "magic_oidc_provider_id": "YOUR_OIDC_PROVIDER_ID",
    "issuer": "https://your-auth-provider.com",
    "audience": "your-app-audience",
    "jwks_url": "https://your-auth-provider.com/.well-known/jwks.json"
  }'

​
Authentication

UOA requires a JWT (Authorization header) and your Magic secret key (X-MAGIC-SECRET-KEY header) on every authenticated request. Your application is responsible for generating the end-user JWT. Include both the user’s JWT and your Magic secret key on every request: 
Authorization: Bearer <USER_JWT_TOKEN>
X-MAGIC-SECRET-KEY: <YOUR_MAGIC_SECRET_KEY>
The X-MAGIC-SECRET-KEY is a server-side secret. Never expose it in client-side code. Use a backend proxy to forward requests to UOA.

​
Create an Account

Create or fetch a user account. This provisions wallet addresses 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: 
{
  "success": true,
  "app_user_id": "user-123",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "public_address": {
    "ETH": "0x1234567890abcdef1234567890abcdef12345678",
    "SOL": "7nYB5F2xVT9hVjhxUoZ5HQxvPz2kTmSoQvGPmxfTjKN"
  },
  "perp_dex_status": {}
}
Calling POST /account multiple times for the same user returns the same account. Wallet addresses are derived deterministically.

​
Fetch Wallet Balances

Use the wallet addresses returned from POST /account to fetch wallet balances directly from your frontend or backend using your preferred EVM and Solana RPC providers.

​
Initialize a Perp DEX

Perp DEX setup has three high-level steps:
  1. Initialize the venue account with POST /account/init-perp-dex.
  2. Make an initial deposit if the venue requires funding before trading setup.
  3. Initialize trading with POST /account/init-perp-dex-trading.
First, check if the requirements are met:
cURL
curl -X POST 'https://uoa-server.magic.xyz/account/check-perp-dex-requirements' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer USER_JWT_TOKEN' \
  -H 'X-MAGIC-SECRET-KEY: YOUR_MAGIC_SECRET_KEY' \
  -d '{
    "dex": "hyperliquid"
  }'
Then initialize:
cURL
curl -X POST 'https://uoa-server.magic.xyz/account/init-perp-dex' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer USER_JWT_TOKEN' \
  -H 'X-MAGIC-SECRET-KEY: YOUR_MAGIC_SECRET_KEY' \
  -d '{
    "dex": "hyperliquid"
  }'
Response: 
{
  "success": true,
  "dex": "hyperliquid",
  "status": {
    "initialized": true,
    "onboarded_at": "2026-04-01T12:00:00Z"
  },
  "message": "Hyperliquid initialized successfully"
}
Use the returned status and venue requirements to decide whether the user needs an initial deposit before trading setup. After the account is initialized and funded, initialize trading:
cURL
curl -X POST 'https://uoa-server.magic.xyz/account/init-perp-dex-trading' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer USER_JWT_TOKEN' \
  -H 'X-MAGIC-SECRET-KEY: YOUR_MAGIC_SECRET_KEY' \
  -d '{
    "dex": "hyperliquid"
  }'

​
Execute a Transfer

Create a transfer to move funds between locations. UOA plans the route and executes it asynchronously.

​
Estimate Costs

Before executing, estimate the transfer cost:
cURL
curl -X POST 'https://uoa-server.magic.xyz/transfer/estimate-transfer-cost' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer USER_JWT_TOKEN' \
  -H 'X-MAGIC-SECRET-KEY: YOUR_MAGIC_SECRET_KEY' \
  -d '{
    "source": "self",
    "destination": "hyperliquid",
    "amount": "100",
    "chain": "ARB",
    "token": "USDC"
  }'

​
Create the Transfer

cURL
curl -X POST 'https://uoa-server.magic.xyz/transfer' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer USER_JWT_TOKEN' \
  -H 'X-MAGIC-SECRET-KEY: YOUR_MAGIC_SECRET_KEY' \
  -d '{
    "source": "self",
    "destination": "hyperliquid",
    "amount": "100",
    "chain": "ARB",
    "token": "USDC"
  }'
Response: 
{
  "success": true,
  "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "message": "Transfer task created. Monitor progress with task_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

​
Monitor Progress

Poll the task to track execution:
cURL
curl -X GET 'https://uoa-server.magic.xyz/task/a1b2c3d4-e5f6-7890-abcd-ef1234567890' \
  -H 'Authorization: Bearer USER_JWT_TOKEN' \
  -H 'X-MAGIC-SECRET-KEY: YOUR_MAGIC_SECRET_KEY'
Response: 
{
  "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "source": "self",
  "destination": "hyperliquid",
  "amount": "100",
  "chain": "ARB",
  "token": "USDC",
  "status": "completed",
  "progress": {
    "current_step": 2,
    "total_steps": 2,
    "steps": [
      { "action": "approve", "status": "completed" },
      { "action": "deposit", "status": "completed" }
    ]
  }
}

​
Next Steps

API Reference

Explore the complete API surface including all endpoints, parameters, and response schemas.

Express API

Learn about the underlying Express API that powers UOA wallet operations.