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

# Transfers & Tasks

> API reference for UOA transfer operations including cost estimation, transfer execution, and task management.

## Authentication

All endpoints require the following headers unless otherwise noted:

<ParamField header="Authorization" type="string" required>
  Bearer token (JWT) for end-user authentication. Format: `Bearer YOUR_JWT_TOKEN`
</ParamField>

<ParamField header="X-MAGIC-SECRET-KEY" type="string" required>
  Your Magic secret key for application-level authentication.
</ParamField>

***

## Estimate Transfer Cost

Estimate the cost of a transfer route before executing it.

```bash cURL icon="square-terminal" theme={null}
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:**

```json theme={null}
{
  "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

<ParamField body="source" type="string" required>
  Where to transfer from. Values: `self`, `extended`, `hyperliquid`, `paradex`, `nado`, `polymarket`
</ParamField>

<ParamField body="destination" type="string" required>
  Where to transfer to. Values: `self`, `extended`, `hyperliquid`, `paradex`, `nado`, `polymarket`
</ParamField>

<ParamField body="amount" type="string" required>
  The amount to transfer as a decimal string (e.g., `"100"`).
</ParamField>

<ParamField body="chain" type="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.
</ParamField>

<ParamField body="token" type="string" default="USDC">
  The token to transfer. Values: `ETH`, `USDC`, `USDC.E`, `POL`, `SOL`
</ParamField>

<ParamField body="destination_chain" type="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`).
</ParamField>

<ParamField body="destination_token" type="string">
  Destination token for transfers to `self`. Required with `destination_chain` for self-to-self transfers. Values: `ETH`, `USDC`, `USDC.E`, `POL`, `SOL`
</ParamField>

<ParamField body="gas_sponsored" type="boolean" default="false">
  Whether to use gas-sponsored execution when supported (EVM only; Solana is never gas-sponsored in this stack).
</ParamField>

### Response Fields

<ResponseField name="success" type="boolean">
  Whether the estimate was computed successfully.
</ResponseField>

<ResponseField name="source" type="string">
  Echo of the request `source` (`self` or a venue id).
</ResponseField>

<ResponseField name="destination" type="string">
  Echo of the request `destination`.
</ResponseField>

<ResponseField name="amount" type="string">
  Echo of the request `amount`.
</ResponseField>

<ResponseField name="steps" type="array">
  List of planned transfer steps with individual cost breakdowns.

  <Expandable title="Step fields">
    <ResponseField name="action" type="string">
      The transfer action: `deposit`, `withdrawal`, or `bridge`.
    </ResponseField>

    <ResponseField name="dex" type="string">
      Venue or bridge component for this step: a perp id (`extended`, `hyperliquid`, `paradex`, `nado`, `polymarket`) or bridge provider such as `lifi`.
    </ResponseField>

    <ResponseField name="cost_eth" type="string">
      Estimated cost in ETH.
    </ResponseField>

    <ResponseField name="cost_usdc" type="string">
      Estimated cost in USDC.
    </ResponseField>

    <ResponseField name="breakdown" type="object">
      Per-step cost breakdown: `gas_cost_eth`, `bridge_fee_usdc`, and `platform_fee_usdc` (decimal strings).
    </ResponseField>

    <ResponseField name="estimated_gas" type="integer | null">
      Optional gas units estimate for the step.
    </ResponseField>

    <ResponseField name="gas_breakdown" type="object | null">
      Optional extended gas detail when the estimator provides it.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total_cost_eth" type="string">
  Total estimated cost across all steps in ETH.
</ResponseField>

<ResponseField name="total_cost_usdc" type="string">
  Total estimated cost across all steps in USDC.
</ResponseField>

<ResponseField name="gas_sponsored" type="boolean">
  Whether the estimate used gas-sponsored execution.
</ResponseField>

<ResponseField name="message" type="string | null">
  Optional human-readable note from the estimator (e.g. errors or caveats).
</ResponseField>

<ResponseField name="route" type="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.
</ResponseField>

***

## Create Transfer

Create and execute a transfer task. The transfer is executed asynchronously. Use the returned `task_id` to monitor progress.

```bash cURL icon="square-terminal" theme={null}
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:**

```json theme={null}
{
  "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](#estimate-transfer-cost) (`source`, `destination`, `amount`, optional `chain`, `token`, `destination_chain`, `destination_token`, `gas_sponsored`).

### Response Fields

<ResponseField name="success" type="boolean">
  Whether the task was created successfully.
</ResponseField>

<ResponseField name="task_id" type="string">
  The UUID of the created transfer task. Use this to poll for status.
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable status message.
</ResponseField>

***

## List Tasks

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

```bash cURL icon="square-terminal" theme={null}
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:**

```json theme={null}
{
  "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

<ParamField query="limit" type="integer" default="5">
  Maximum number of tasks to return.
</ParamField>

### Response Fields

<ResponseField name="user_id" type="string">
  The UOA-internal user UUID.
</ResponseField>

<ResponseField name="tasks" type="array">
  List of task objects.

  <Expandable title="Task fields">
    <ResponseField name="task_id" type="string">
      The task UUID.
    </ResponseField>

    <ResponseField name="source" type="string">
      Transfer source location.
    </ResponseField>

    <ResponseField name="destination" type="string">
      Transfer destination location.
    </ResponseField>

    <ResponseField name="amount" type="string">
      Transfer amount as a decimal string.
    </ResponseField>

    <ResponseField name="chain" type="string">
      Chain code for the transfer.
    </ResponseField>

    <ResponseField name="token" type="string">
      Token code for the transfer.
    </ResponseField>

    <ResponseField name="status" type="string">
      Task status: `pending`, `in_progress`, `completed`, `failed`, or `cancelled`.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of task creation.
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO 8601 timestamp of last update.
    </ResponseField>

    <ResponseField name="progress" type="object">
      Step-level execution progress. Shape varies by route and executor.
    </ResponseField>

    <ResponseField name="metadata" type="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.
    </ResponseField>
  </Expandable>
</ResponseField>

***

## Get Task

Get a specific transfer task by ID.

```bash cURL icon="square-terminal" theme={null}
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:**

```json theme={null}
{
  "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

<ParamField path="task_id" type="string" required>
  The UUID of the task to retrieve.
</ParamField>

### Response Fields

The response fields are the same as those in the [List Tasks](#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](#create-transfer) (`success`, `task_id`, `message`). Not allowed for `pending`, `in_progress`, or `completed` tasks.

```bash cURL icon="square-terminal" theme={null}
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:**

```json theme={null}
{
  "success": true,
  "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "message": "Task a1b2c3d4-e5f6-7890-abcd-ef1234567890 is being resumed from step 0"
}
```