Skip to main content

​
Authentication

All endpoints require the following headers unless otherwise noted:
​
Authorization
string
required
Bearer token (JWT) for end-user authentication. Format: Bearer YOUR_JWT_TOKEN
​
X-MAGIC-SECRET-KEY
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",
  "message": null,
  "route": null
}

​
Request Parameters

​
source
string
required
Where to transfer from. Values: self, extended, hyperliquid, paradex, nado, polymarket
​
destination
string
required
Where to transfer to. Values: self, extended, hyperliquid, paradex, nado, polymarket
​
amount
string
required
The amount to transfer as a decimal string (e.g., "100").
​
chain
string
default:"ARB"
The chain context for the transfer. Values: ETH, ARB, POL, SOL, STRK, INK
​
token
string
default:"USDC"
The token to transfer. Values: ETH, WETH, USDC, USDC.E, POL, SOL
​
transfer_mode
string
Optional transfer mode. Values: sponsored (gas-sponsored), legacy

​
Response Fields

​
success
boolean
Whether the estimate was computed successfully.
​
steps
array
List of planned transfer steps with individual cost breakdowns.
​
total_cost_eth
string
Total estimated cost across all steps in ETH.
​
total_cost_usdc
string
Total estimated cost across all steps in USDC.

​
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 and executing"
}
The response also includes an X-Task-ID header for convenience.

​
Request Parameters

The request parameters are identical to Estimate Transfer Cost.

​
Response Fields

​
success
boolean
Whether the task was created successfully.
​
task_id
string
The UUID of the created transfer task. Use this to poll for status.
​
message
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": null
    }
  ]
}

​
Query Parameters

​
limit
integer
default:"5"
Maximum number of tasks to return.

​
Response Fields

​
user_id
string
The UOA-internal user UUID.
​
tasks
array
List of task objects.

​
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": null
}

​
Path Parameters

​
task_id
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.

​
Resume Task

Resume a failed or cancelled transfer task from the last successful checkpoint.
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 resumed"
}

​
Path Parameters

​
task_id
string
required
The UUID of the task to resume.
Only tasks with status FAILED or CANCELLED can be resumed. Attempting to resume a COMPLETED, IN_PROGRESS, or PENDING task will return an error.

​
Response Fields

​
success
boolean
Whether the task was resumed successfully.
​
task_id
string
The UUID of the resumed task.
​
message
string
Human-readable status message.