Developer Docs

Prerequisites

Before using UOA, you need:

Create a Magic Account

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

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.

Set up authentication

Configure your application to issue JWTs for end users.

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.

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:

Initialize the venue account with POST /account/init-perp-dex.
Make an initial deposit if the venue requires funding before trading setup.
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.

Unified Orchestration Accounts

API Reference

Getting Started

Prerequisites

Authentication

Create an Account

Fetch Wallet Balances

Initialize a Perp DEX

Execute a Transfer

Estimate Costs

Create the Transfer

Monitor Progress

Next Steps

API Reference

Express API

​Prerequisites

​Authentication

​Create an Account

​Fetch Wallet Balances

​Initialize a Perp DEX

​Execute a Transfer

​Estimate Costs

​Create the Transfer

​Monitor Progress

​Next Steps

API Reference

Express API

Prerequisites

Authentication

Create an Account

Fetch Wallet Balances

Initialize a Perp DEX

Execute a Transfer

Estimate Costs

Create the Transfer

Monitor Progress

Next Steps