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.