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.
Authentication All endpoints require the following headers unless otherwise noted:
Bearer token (JWT) for end-user authentication. Format: Bearer YOUR_JWT_TOKEN
Your Magic secret key for application-level authentication.
Estimate Transfer Cost Estimate the cost of a transfer route before executing it.
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" }'
Response: { "success" : true , "source" : "self" , "destination" : "hyperliquid" , "amount" : "100" , "steps" : [ { "action" : "deposit" , "dex" : "hyperliquid" , "cost_eth" : "0.0001" , "cost_usdc" : "0.25" , "breakdown" : { "gas_cost_eth" : "0.0001" , "bridge_fee_usdc" : "0" , "platform_fee_usdc" : "0" }, "estimated_gas" : 150000 , "gas_breakdown" : null } ], "total_cost_eth" : "0.0001" , "total_cost_usdc" : "0.25" , "gas_sponsored" : false , "message" : null , "route" : null }
Request Parameters Where to transfer from. Values: self, extended, hyperliquid, paradex, nado, polymarket
Where to transfer to. Values: self, extended, hyperliquid, paradex, nado, polymarket
The amount to transfer as a decimal string (e.g., "100").
The chain context for the transfer (API values match the Chain enum). If source or destination is self, this must be one of ETH, ARB, POL, INK, or SOL (UOA self-wallet policy). Pure venue→venue routes may use other chain contexts where the planner supports them.
The token to transfer. Values: ETH, USDC, USDC.E, POL, SOL
Destination chain for transfers to self. Required with destination_token for self-to-self transfers. Must be one of ETH, ARB, POL, INK, or SOL when used (same self-wallet policy as chain).
Destination token for transfers to self. Required with destination_chain for self-to-self transfers. Values: ETH, USDC, USDC.E, POL, SOL
Whether to use gas-sponsored execution when supported (EVM only; Solana is never gas-sponsored in this stack).
Response Fields Whether the estimate was computed successfully.
Echo of the request source (self or a venue id).
Echo of the request destination.
Echo of the request amount.
List of planned transfer steps with individual cost breakdowns. The transfer action: deposit, withdrawal, or bridge.
Venue or bridge component for this step: a perp id (extended, hyperliquid, paradex, nado, polymarket) or bridge provider such as lifi.
Per-step cost breakdown: gas_cost_eth, bridge_fee_usdc, and platform_fee_usdc (decimal strings).
Optional gas units estimate for the step.
Optional extended gas detail when the estimator provides it.
Total estimated cost across all steps in ETH.
Total estimated cost across all steps in USDC.
Whether the estimate used gas-sponsored execution.
Optional human-readable note from the estimator (e.g. errors or caveats).
When present, a route summary (route_id, reason, hops, steps, gas_policy, chain estimates, optional bridge_estimation_error, effective_minimum_deposit, etc.). Omitted or null when the planner does not attach one.
Create Transfer Create and execute a transfer task. The transfer is executed asynchronously. Use the returned task_id to monitor progress.
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": "extended", "destination": "polymarket", "amount": "50", "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" }
The response also includes an X-Task-ID header for convenience.
Request Parameters The JSON body matches Estimate Transfer Cost (source, destination, amount, optional chain, token, destination_chain, destination_token, gas_sponsored).
Response Fields Whether the task was created successfully.
The UUID of the created transfer task. Use this to poll for status.
Human-readable status message.
List Tasks Get the authenticated user’s transfer tasks, ordered by most recent.
curl -X GET 'https://uoa-server.magic.xyz/tasks?limit=10' \ -H 'Authorization: Bearer USER_JWT_TOKEN' \ -H 'X-MAGIC-SECRET-KEY: YOUR_MAGIC_SECRET_KEY'
Response: { "user_id" : "550e8400-e29b-41d4-a716-446655440000" , "tasks" : [ { "task_id" : "a1b2c3d4-e5f6-7890-abcd-ef1234567890" , "user_id" : "550e8400-e29b-41d4-a716-446655440000" , "source" : "self" , "destination" : "hyperliquid" , "amount" : "100" , "chain" : "ARB" , "token" : "USDC" , "status" : "completed" , "created_at" : "2026-04-01T12:00:00Z" , "updated_at" : "2026-04-01T12:01:30Z" , "progress" : {}, "metadata" : {} } ] }
Query Parameters Maximum number of tasks to return.
Response Fields The UOA-internal user UUID.
List of task objects. Transfer source location.
Transfer destination location.
Transfer amount as a decimal string.
Chain code for the transfer.
Token code for the transfer.
Task status: pending, in_progress, completed, failed, or cancelled.
ISO 8601 timestamp of task creation.
ISO 8601 timestamp of last update.
Step-level execution progress. Shape varies by route and executor.
Additional task metadata (e.g. route plan, execution checkpoints). Sensitive fields such as auth_jwt are never returned; the API strips them before responding.
Get Task Get a specific transfer task by ID.
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" , "user_id" : "550e8400-e29b-41d4-a716-446655440000" , "source" : "self" , "destination" : "hyperliquid" , "amount" : "100" , "chain" : "ARB" , "token" : "USDC" , "status" : "in_progress" , "created_at" : "2026-04-01T12:00:00Z" , "updated_at" : "2026-04-01T12:00:45Z" , "progress" : { "current_step" : 1 , "total_steps" : 2 , "steps" : [ { "action" : "approve" , "status" : "completed" }, { "action" : "deposit" , "status" : "in_progress" } ] }, "metadata" : {} }
Path Parameters The UUID of the task to retrieve.
Response Fields The response fields are the same as those in the List Tasks task object.
For a task still in pending status, the server may enqueue background execution when you fetch it (internal retry using stored credentials).
Resume Task Resume a failed or cancelled transfer task. Returns the same payload shape as Create Transfer (success, task_id, message). Not allowed for pending, in_progress, or completed tasks.
curl -X POST 'https://uoa-server.magic.xyz/task/a1b2c3d4-e5f6-7890-abcd-ef1234567890/resume' \ -H 'Authorization: Bearer USER_JWT_TOKEN' \ -H 'X-MAGIC-SECRET-KEY: YOUR_MAGIC_SECRET_KEY'
Response: { "success" : true , "task_id" : "a1b2c3d4-e5f6-7890-abcd-ef1234567890" , "message" : "Task a1b2c3d4-e5f6-7890-abcd-ef1234567890 is being resumed from step 0" }
