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.
What is Unified Orchestration Accounts?
Unified Orchestration Accounts (UOA) is an orchestration layer built on top of Magic’s Server Wallets. It provides a single API to manage user accounts across multiple blockchains and perpetual DEX venues, plan and execute multi-step fund transfers, and bridge assets cross-chain. UOA handles the complexity of routing funds between wallets and trading venues so you can focus on building your application.Key Benefits
Multi-Chain Wallets
Automatically provision and manage wallets across Ethereum, Arbitrum, Polygon, Starknet, Solana, and Ink from a single account.
Perp DEX Integration
Initialize and manage accounts on Extended, Hyperliquid, Paradex, Nado, and Polymarket with unified deposit, withdrawal, and balance APIs.
Transfer Orchestration
Plan and execute multi-step transfers between wallets and DEX venues with automatic route planning, cost estimation, and fallback strategies.
Cross-Chain Bridging
Bridge assets across chains via LiFi integration with quote, execute, and status tracking built in.
Supported Chains and Tokens
Chains
| Chain | Code | Type |
|---|---|---|
| Ethereum | ETH | EVM |
| Arbitrum | ARB | EVM |
| Polygon | POL | EVM |
| Starknet | STRK | Non-EVM |
| Ink | INK | EVM |
| Solana | SOL | Non-EVM |
Tokens
| Token | Code | Description |
|---|---|---|
| ETH | ETH | Native Ether |
| WETH | WETH | Wrapped Ether |
| USDC | USDC | USD Coin |
| USDC.e | USDC.E | Bridged USDC |
| POL | POL | Native Polygon token |
| SOL | SOL | Native Solana token |
Supported DEX Venues
| Venue | Code | Chain | Notes |
|---|---|---|---|
| Extended | extended | Arbitrum | Magic-backed onboarding |
| Hyperliquid | hyperliquid | Arbitrum | Strict deposit floor + fixed withdrawal fee |
| Paradex | paradex | Arbitrum | Rhino-based bridge transfers |
| Nado | nado | Ink | Wallet-signed operations, no separate onboarding |
| Polymarket | polymarket | Polygon | Prediction market with Gnosis Safe proxy + gasless relayer |
Architecture
UOA sits between your application and the blockchain, providing three layers of functionality:- Account layer — Creates and manages user accounts with wallets across all supported chains. Each user gets one wallet per chain, derived deterministically.
- DEX layer — Initializes and manages perp DEX venue accounts. Handles the venue-specific onboarding flows, credential management, and balance queries.
-
Transfer layer — Plans and executes multi-step transfer routes. A single transfer request (e.g., move USDC from Hyperliquid to Polymarket) is broken down into steps like
dex_withdraw -> bridge_swap -> dex_deposit, executed asynchronously with checkpoint-based resume on failure.
Authentication
All UOA endpoints require two authentication headers:Bearer token (JWT) issued by your application for end-user authentication. Format:
Bearer YOUR_JWT_TOKENYour Magic secret key for application-level authentication.
User authenticates with your app
Your application authenticates the user (e.g., via Magic Link, OAuth, or any identity provider) and issues a JWT.
Configure your identity provider
Register your JWT issuer, audience, and JWKS URL with UOA so it can validate your tokens.
Send authenticated requests
Include both the user’s JWT (
Authorization: Bearer ...) and your Magic secret key (X-MAGIC-SECRET-KEY) on every request.Transfer Execution Model
Transfers are modeled as asynchronous, resumable tasks. When you create a transfer, UOA:- Plans the route — Determines the steps needed (withdraw, bridge, deposit) with fallback routes
- Creates a task — Returns a
task_idimmediately so you can track progress - Executes asynchronously — Runs each step in sequence, persisting progress at each checkpoint
- Supports resume — If a step fails, you can resume the task from the last successful checkpoint
Transfer Step Types
| Step | Description |
|---|---|
withdrawal | Withdraw funds from a perp venue to the user’s wallet |
bridge | Cross-chain bridge transfer (powered by LiFi) |
deposit | Deposit funds into a perp venue |
Task Statuses
| Status | Description |
|---|---|
PENDING | Task created, awaiting execution |
IN_PROGRESS | Currently executing transfer steps |
COMPLETED | All steps finished successfully |
FAILED | A step failed (can be resumed) |
CANCELLED | Task was cancelled (can be resumed) |
Next Steps
Getting Started
Set up your first UOA integration with step-by-step instructions.
API Reference
Explore the complete API surface for accounts, transfers, wallets, and more.