Developer Docs

Authentication

All endpoints require the following headers unless otherwise noted:

string

required

Bearer token (JWT) for end-user authentication. Format: Bearer YOUR_JWT_TOKEN

string

required

Your Magic secret key for application-level authentication.

Estimate Transfer Cost

Estimate the cost of a transfer route before executing it.

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"
  }'

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

string

required

Where to transfer from. Values: self, extended, hyperliquid, paradex, nado, polymarket

string

required

Where to transfer to. Values: self, extended, hyperliquid, paradex, nado, polymarket

string

required

The amount to transfer as a decimal string (e.g., "100").

string

default:"ARB"

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.

string

default:"USDC"

The token to transfer. Values: ETH, USDC, USDC.E, POL, SOL

string

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).

string

Destination token for transfers to self. Required with destination_chain for self-to-self transfers. Values: ETH, USDC, USDC.E, POL, SOL

boolean

default:"false"

Whether to use gas-sponsored execution when supported (EVM only; Solana is never gas-sponsored in this stack).

Response Fields

boolean

Whether the estimate was computed successfully.

string

Echo of the request source (self or a venue id).

string

Echo of the request destination.

string

Echo of the request amount.

array

List of planned transfer steps with individual cost breakdowns.

Show Step fields

string

The transfer action: deposit, withdrawal, or bridge.

string

Venue or bridge component for this step: a perp id (extended, hyperliquid, paradex, nado, polymarket) or bridge provider such as lifi.

string

Estimated cost in ETH.

string

Estimated cost in USDC.

object

Per-step cost breakdown: gas_cost_eth, bridge_fee_usdc, and platform_fee_usdc (decimal strings).

integer | null

Optional gas units estimate for the step.

object | null

Optional extended gas detail when the estimator provides it.

string

Total estimated cost across all steps in ETH.

string

Total estimated cost across all steps in USDC.

boolean

Whether the estimate used gas-sponsored execution.

string | null

Optional human-readable note from the estimator (e.g. errors or caveats).

object | null

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

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

boolean

Whether the task was created successfully.

string

The UUID of the created transfer task. Use this to poll for status.

string

Human-readable status message.

List Tasks

Get the authenticated user’s transfer tasks, ordered by most recent.

cURL

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

integer

default:"5"

Maximum number of tasks to return.

Response Fields

string

The UOA-internal user UUID.

array

List of task objects.

Show Task fields

string

The task UUID.

string

Transfer source location.

string

Transfer destination location.

string

Transfer amount as a decimal string.

string

Chain code for the transfer.

string

Token code for the transfer.

string

Task status: pending, in_progress, completed, failed, or cancelled.

string

ISO 8601 timestamp of task creation.

string

ISO 8601 timestamp of last update.

object

Step-level execution progress. Shape varies by route and executor.

object

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

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

string

required

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

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"
}

Unified Orchestration Accounts

API Reference

Transfers & Tasks

Authentication

Estimate Transfer Cost

Request Parameters

Response Fields

Create Transfer

Request Parameters

Response Fields

List Tasks

Query Parameters

Response Fields

Get Task

Path Parameters

Response Fields

Resume Task

​Authentication

​Estimate Transfer Cost

​Request Parameters

​Response Fields

​Create Transfer

​Request Parameters

​Response Fields

​List Tasks

​Query Parameters

​Response Fields

​Get Task

​Path Parameters

​Response Fields

​Resume Task

Authentication

Estimate Transfer Cost

Request Parameters

Response Fields

Create Transfer

Request Parameters

Response Fields

List Tasks

Query Parameters

Response Fields

Get Task

Path Parameters

Response Fields

Resume Task