Skip to main content

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.

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

​
Check DEX Requirements

Check whether the authenticated user meets the requirements to initialize a perp DEX venue (e.g., minimum balance, gas availability).
cURL
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: 
{
  "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

​
dex
string
required
The DEX venue to check. Values: extended, hyperliquid, paradex, nado, polymarket

​
Response Fields

​
success
boolean
Whether the check completed successfully.
​
dex
string
The DEX venue that was checked.
​
requirements_met
boolean
Whether all requirements are satisfied for initialization.
​
requirements
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.
​
message
string
Human-readable status message.

​
Initialize DEX

Initialize a perp DEX venue for the authenticated user. This handles venue-specific account creation and onboarding.
cURL
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: 
{
  "success": true,
  "dex": "hyperliquid",
  "status": {
    "initialized": true,
    "account_address": "0x1234567890abcdef1234567890abcdef12345678"
  },
  "message": "Hyperliquid has been initialized"
}

​
Request Parameters

​
dex
string
required
The DEX venue to initialize. Values: extended, hyperliquid, paradex, nado, polymarket
​
force_reinit
boolean
default:"false"
Force re-initialization even if the venue is already set up.
​
metadata
object
Optional venue-specific initialization metadata.

​
Response Fields

​
success
boolean
Whether initialization completed successfully.
​
dex
string
The DEX venue that was initialized.
​
status
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.
​
message
string
Human-readable status message.

​
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.
cURL
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: 
{
  "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

​
dex
string
required
The DEX venue to initialize for trading. Values: extended, hyperliquid, paradex, nado, polymarket
​
metadata
object
Optional venue-specific trading setup metadata. Hyperliquid accepts agent_name, builder_address, and max_builder_fee_rate; Paradex and Nado accept name.
​
force_reinit
boolean
default:"false"
Force trading setup even if the venue is already trade-initialized.

​
Response Fields

​
success
boolean
Whether trading setup completed successfully.
​
dex
string
The DEX venue that was initialized for trading.
​
message
string
Human-readable status message.
​
status
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.

​
Get DEX Assets

Get perp DEX asset state including balances and transfer rules for a specific venue.
cURL
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: 
{
  "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

​
dex
string
required
The DEX venue to query. Values: extended, hyperliquid, paradex, nado, polymarket

​
Response Fields

​
dex
string
The DEX venue queried.
​
initialized
boolean
Whether the venue is initialized for this user.
​
assets
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.
​
transfer_rules
object
Deposit and withdrawal rules including minimum amounts and fees. null if not initialized.
​
error
string
Error message if the query failed. null on success.

​
Get DEX Credentials

Get platform-specific API credentials for the authenticated user’s DEX account.
cURL
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: 
{
  "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

​
dex
string
required
The DEX venue to query credentials for. Values: extended, hyperliquid, paradex, nado, polymarket

​
Response Fields

​
dex
string
The DEX venue queried.
​
initialized
boolean
Whether the venue is initialized for this user.
​
trade_initialized
boolean
Whether post-funding trading setup has completed for this venue.
​
error
string
Error message if the query failed. null on success.
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.