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

# Perp DEX

> API reference for UOA perpetual DEX venue management including initialization, balances, and credentials.

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

***

## Check DEX Requirements

Check whether the authenticated user meets the requirements to initialize a perp DEX venue (e.g., minimum balance, gas availability).

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

**Response:**

```json theme={null}
{
  "success": true,
  "dex": "hyperliquid",
  "requirements_met": true,
  "requirements": {
    "requirements_met": true,
    "message": "All Hyperliquid requirements met",
    "usdc_required": "0",
    "usdc_available": "12.5",
    "usdc_sufficient": true,
    "chain_balances": {
      "ARB": "12.5"
    },
    "eth_required": "0",
    "eth_available": "0",
    "eth_sufficient": true
  },
  "message": "Requirements check completed successfully"
}
```

### Request Parameters

<ParamField body="dex" type="string" required>
  The DEX venue to check. Values: `extended`, `hyperliquid`, `paradex`, `nado`, `polymarket`
</ParamField>

### Response Fields

<ResponseField name="success" type="boolean">
  Whether the check completed successfully.
</ResponseField>

<ResponseField name="dex" type="string">
  The DEX venue that was checked.
</ResponseField>

<ResponseField name="requirements_met" type="boolean">
  Whether all requirements are satisfied for initialization.
</ResponseField>

<ResponseField name="requirements" type="object">
  Detailed requirements breakdown. Common fields include `requirements_met`, `message`, `usdc_required`, `usdc_available`, `usdc_sufficient`, `chain_balances`, `eth_required`, `eth_available`, and `eth_sufficient`; venues may add fields.
</ResponseField>

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

***

## Initialize DEX

Initialize a perp DEX venue for the authenticated user. This handles venue-specific account creation and onboarding.

```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",
    "force_reinit": false
  }'
```

**Response:**

```json theme={null}
{
  "success": true,
  "dex": "hyperliquid",
  "status": {
    "initialized": true,
    "account_address": "0x1234567890abcdef1234567890abcdef12345678"
  },
  "message": "Hyperliquid has been initialized"
}
```

### Request Parameters

<ParamField body="dex" type="string" required>
  The DEX venue to initialize. Values: `extended`, `hyperliquid`, `paradex`, `nado`, `polymarket`
</ParamField>

<ParamField body="force_reinit" type="boolean" default="false">
  Force re-initialization even if the venue is already set up.
</ParamField>

<ParamField body="metadata" type="object">
  Optional venue-specific initialization metadata.
</ParamField>

### Response Fields

<ResponseField name="success" type="boolean">
  Whether initialization completed successfully.
</ResponseField>

<ResponseField name="dex" type="string">
  The DEX venue that was initialized.
</ResponseField>

<ResponseField name="status" type="object">
  Venue-specific initialization status persisted for the user's account. For example, Hyperliquid includes `initialized` and `account_address`; Extended, Paradex, Nado, and Polymarket include their own account configuration fields.
</ResponseField>

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

***

## Initialize Trading

Initialize venue-specific trading setup after the account is initialized and funded. Some venues require an initial deposit before trading credentials or signer setup can be completed.

```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",
    "force_reinit": false
  }'
```

**Response:**

```json theme={null}
{
  "success": true,
  "dex": "hyperliquid",
  "message": "Hyperliquid trading initialization completed",
  "status": {
    "trade_initialized": true,
    "agent_address": "0x1234567890abcdef1234567890abcdef12345678",
    "agent_name": "default",
    "builder_address": null,
    "max_builder_fee_rate": null,
    "agent_private_key": "0x..."
  }
}
```

### Request Parameters

<ParamField body="dex" type="string" required>
  The DEX venue to initialize for trading. Values: `extended`, `hyperliquid`, `paradex`, `nado`, `polymarket`
</ParamField>

<ParamField body="metadata" type="object">
  Optional venue-specific trading setup metadata. Hyperliquid accepts `agent_name`, `builder_address`, and `max_builder_fee_rate`; Paradex and Nado accept `name`.
</ParamField>

<ParamField body="force_reinit" type="boolean" default="false">
  Force trading setup even if the venue is already trade-initialized.
</ParamField>

### Response Fields

<ResponseField name="success" type="boolean">
  Whether trading setup completed successfully.
</ResponseField>

<ResponseField name="dex" type="string">
  The DEX venue that was initialized for trading.
</ResponseField>

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

<ResponseField name="status" type="object">
  Venue-specific trading setup status. Some fields are returned only once in this response and are not persisted, such as Hyperliquid `agent_private_key`, Extended `stark_private_key`, Paradex `subkey_private_key`, and Nado `linked_signer_private_key`.
</ResponseField>

***

## Get DEX Assets

Get perp DEX asset state including balances and transfer rules for a specific venue.

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

**Response:**

```json theme={null}
{
  "dex": "hyperliquid",
  "initialized": true,
  "assets": {
    "balance": "500.00",
    "account_value": "512.50",
    "available_for_withdrawal": "500.00"
  },
  "transfer_rules": {
    "chain": "ARB",
    "token": "USDC",
    "deposit": {
      "supported": true,
      "minimum_amount": "5",
      "fee": {
        "amount": "0",
        "token": "USDC",
        "fee_type": "fixed",
        "note": "Deposits below 5 USDC can be lost by the perp dex."
      },
      "note": "Deposits below 5 USDC can be lost by the perp dex."
    },
    "withdrawal": {
      "supported": true,
      "minimum_amount": "1",
      "fee": {
        "amount": "0",
        "token": "USDC",
        "fee_type": "fixed",
        "note": null
      },
      "note": null
    }
  },
  "error": null
}
```

### Query Parameters

<ParamField query="dex" type="string" required>
  The DEX venue to query. Values: `extended`, `hyperliquid`, `paradex`, `nado`, `polymarket`
</ParamField>

### Response Fields

<ResponseField name="dex" type="string">
  The DEX venue queried.
</ResponseField>

<ResponseField name="initialized" type="boolean">
  Whether the venue is initialized for this user.
</ResponseField>

<ResponseField name="assets" type="object">
  Shared asset fields from the venue: `balance`, `account_value`, and `available_for_withdrawal`. Polymarket may also include `proxy_wallet_usdc_e` and `proxy_wallet_pusd`. `null` if not initialized.
</ResponseField>

<ResponseField name="transfer_rules" type="object">
  Deposit and withdrawal rules including minimum amounts and fees. `null` if not initialized.

  <Expandable title="transfer_rules fields">
    <ResponseField name="chain" type="string">
      The chain used for deposits/withdrawals.
    </ResponseField>

    <ResponseField name="token" type="string">
      The token used for deposits/withdrawals.
    </ResponseField>

    <ResponseField name="deposit" type="object">
      Deposit rules: `supported`, `minimum_amount`, `fee`, and `note`.
    </ResponseField>

    <ResponseField name="withdrawal" type="object">
      Withdrawal rules: `supported`, `minimum_amount`, `fee`, and `note`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="error" type="string">
  Error message if the query failed. `null` on success.
</ResponseField>

***

## Get DEX Credentials

Get platform-specific API credentials for the authenticated user's DEX account.

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

**Response:**

```json theme={null}
{
  "dex": "hyperliquid",
  "initialized": true,
  "trade_initialized": true,
  "agent_name": "default",
  "agent_address": "0x1234567890abcdef1234567890abcdef12345678",
  "builder_address": null,
  "max_builder_fee_rate": null,
  "error": null
}
```

### Query Parameters

<ParamField query="dex" type="string" required>
  The DEX venue to query credentials for. Values: `extended`, `hyperliquid`, `paradex`, `nado`, `polymarket`
</ParamField>

### Response Fields

<ResponseField name="dex" type="string">
  The DEX venue queried.
</ResponseField>

<ResponseField name="initialized" type="boolean">
  Whether the venue is initialized for this user.
</ResponseField>

<ResponseField name="trade_initialized" type="boolean">
  Whether post-funding trading setup has completed for this venue.
</ResponseField>

<ResponseField name="error" type="string">
  Error message if the query failed. `null` on success.
</ResponseField>

<Info>
  Additional credential fields are venue-specific and vary by DEX. This endpoint returns persisted credential metadata only; one-time private keys are returned from `POST /account/init-perp-dex-trading`.
</Info>