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

# Getting Started

> Set up Unified Orchestration Accounts with step-by-step instructions for authentication, account creation, and your first transfer.

## Prerequisites

Before using UOA, you need:

<Steps>
  <Step title="Create a Magic Account">
    Visit the [Magic Dashboard](https://dashboard.magic.link) and sign up for a Magic developer account.
  </Step>

  <Step title="Get your API keys">
    In your dashboard, create a new application and obtain your **Secret Key**. You will use this as the `X-MAGIC-SECRET-KEY` header on all requests.
  </Step>

  <Step title="Set up authentication">
    Configure your application to issue JWTs for end users.
  </Step>

  <Step title="Set up Server Wallets">
    Follow the dashboard guide to set up Server Wallets for your application. Use the same Magic credential and returned provider ID when registering your UOA wallet setup.
  </Step>

  <Step title="Register your app with UOA">
    Register your application with your Magic secret key and OIDC configuration so UOA can validate your user JWTs.

    ```bash cURL icon="square-terminal" theme={null}
    curl -X POST 'https://uoa-server.magic.xyz/apps' \
      -H 'Content-Type: application/json' \
      -d '{
        "name": "My App",
        "magic_app_secret_key": "sk-live-XXXXXXXX",
        "magic_oidc_provider_id": "YOUR_OIDC_PROVIDER_ID",
        "issuer": "https://your-auth-provider.com",
        "audience": "your-app-audience",
        "jwks_url": "https://your-auth-provider.com/.well-known/jwks.json"
      }'
    ```
  </Step>
</Steps>

## Authentication

UOA requires a JWT (`Authorization` header) and your Magic secret key (`X-MAGIC-SECRET-KEY` header) on every authenticated request. Your application is responsible for generating the end-user JWT.

Include both the user's JWT and your Magic secret key on every request:

```bash theme={null}
Authorization: Bearer <USER_JWT_TOKEN>
X-MAGIC-SECRET-KEY: <YOUR_MAGIC_SECRET_KEY>
```

<Warning>
  The `X-MAGIC-SECRET-KEY` is a server-side secret. Never expose it in client-side code. Use a backend proxy to forward requests to UOA.
</Warning>

## Create an Account

Create or fetch a user account. This provisions wallet addresses for supported EVM and Solana chains.

```bash cURL icon="square-terminal" theme={null}
curl -X POST 'https://uoa-server.magic.xyz/account' \
  -H 'Authorization: Bearer USER_JWT_TOKEN' \
  -H 'X-MAGIC-SECRET-KEY: YOUR_MAGIC_SECRET_KEY'
```

**Response:**

```json theme={null}
{
  "success": true,
  "app_user_id": "user-123",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "public_address": {
    "ETH": "0x1234567890abcdef1234567890abcdef12345678",
    "SOL": "7nYB5F2xVT9hVjhxUoZ5HQxvPz2kTmSoQvGPmxfTjKN"
  },
  "perp_dex_status": {}
}
```

<Info>
  Calling `POST /account` multiple times for the same user returns the same account. Wallet addresses are derived deterministically.
</Info>

## Fetch Wallet Balances

Use the wallet addresses returned from `POST /account` to fetch wallet balances directly from your frontend or backend using your preferred EVM and Solana RPC providers.

## Initialize a Perp DEX

Perp DEX setup has three high-level steps:

1. Initialize the venue account with `POST /account/init-perp-dex`.
2. Make an initial deposit if the venue requires funding before trading setup.
3. Initialize trading with `POST /account/init-perp-dex-trading`.

First, check if the requirements are met:

```bash cURL icon="square-terminal" theme={null}
curl -X POST 'https://uoa-server.magic.xyz/account/check-perp-dex-requirements' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer USER_JWT_TOKEN' \
  -H 'X-MAGIC-SECRET-KEY: YOUR_MAGIC_SECRET_KEY' \
  -d '{
    "dex": "hyperliquid"
  }'
```

Then initialize:

```bash cURL icon="square-terminal" theme={null}
curl -X POST 'https://uoa-server.magic.xyz/account/init-perp-dex' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer USER_JWT_TOKEN' \
  -H 'X-MAGIC-SECRET-KEY: YOUR_MAGIC_SECRET_KEY' \
  -d '{
    "dex": "hyperliquid"
  }'
```

**Response:**

```json theme={null}
{
  "success": true,
  "dex": "hyperliquid",
  "status": {
    "initialized": true,
    "onboarded_at": "2026-04-01T12:00:00Z"
  },
  "message": "Hyperliquid initialized successfully"
}
```

Use the returned status and venue requirements to decide whether the user needs an initial deposit before trading setup.

After the account is initialized and funded, initialize trading:

```bash cURL icon="square-terminal" theme={null}
curl -X POST 'https://uoa-server.magic.xyz/account/init-perp-dex-trading' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer USER_JWT_TOKEN' \
  -H 'X-MAGIC-SECRET-KEY: YOUR_MAGIC_SECRET_KEY' \
  -d '{
    "dex": "hyperliquid"
  }'
```

## Execute a Transfer

Create a transfer to move funds between locations. UOA plans the route and executes it asynchronously.

### Estimate Costs

Before executing, estimate the transfer cost:

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

### Create the Transfer

```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": "self",
    "destination": "hyperliquid",
    "amount": "100",
    "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"
}
```

### Monitor Progress

Poll the task to track execution:

```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",
  "source": "self",
  "destination": "hyperliquid",
  "amount": "100",
  "chain": "ARB",
  "token": "USDC",
  "status": "completed",
  "progress": {
    "current_step": 2,
    "total_steps": 2,
    "steps": [
      { "action": "approve", "status": "completed" },
      { "action": "deposit", "status": "completed" }
    ]
  }
}
```

## Next Steps

<CardGroup cols={2}>
  <Card title="API Reference" icon="code" href="/uoa/api-reference/accounts">
    Explore the complete API surface including all endpoints, parameters, and response schemas.
  </Card>

  <Card title="Express API" icon="rocket" href="/server-wallets/express-api/overview">
    Learn about the underlying Express API that powers UOA wallet operations.
  </Card>
</CardGroup>