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.

​
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": {
    "min_balance": "5.00",
    "has_gas": true
  },
  "message": "All requirements met"
}

​
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 (venue-specific).
​
message
string
Human-readable status message.

​
Initialize DEX

Initialize a perp DEX venue for the authenticated user. This handles venue-specific onboarding flows.
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,
    "onboarded_at": "2026-04-01T12:00:00Z"
  },
  "message": "Hyperliquid initialized successfully"
}

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

​
Response Fields

​
success
boolean
Whether initialization completed successfully.
​
dex
string
The DEX venue that was initialized.
​
status
object
Venue-specific initialization status.
​
message
string
Human-readable status message.

​
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": {
    "USDC": "500.00",
    "unrealized_pnl": "12.50"
  },
  "transfer_rules": {
    "chain": "ARB",
    "token": "USDC",
    "deposit": {
      "supported": true,
      "minimum_amount": "5.00",
      "fee": {
        "amount": "0",
        "token": "USDC",
        "fee_type": "none",
        "note": null
      },
      "note": null
    },
    "withdrawal": {
      "supported": true,
      "minimum_amount": "1.00",
      "fee": {
        "amount": "1.00",
        "token": "USDC",
        "fee_type": "fixed",
        "note": "Fixed withdrawal fee"
      },
      "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
Token balances and positions on the venue. 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,
  "api_key": "...",
  "api_secret": "...",
  "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.
​
error
string
Error message if the query failed. null on success.
Additional credential fields are venue-specific and vary by DEX.

​
Get DEX Transfer History

Get DEX-native transfer history for the authenticated user.
cURL
curl -X GET 'https://uoa-server.magic.xyz/account/perp-dex-transfers?dex=hyperliquid' \
  -H 'Authorization: Bearer USER_JWT_TOKEN' \
  -H 'X-MAGIC-SECRET-KEY: YOUR_MAGIC_SECRET_KEY'
Response: 
{
  "dex": "hyperliquid",
  "results": [
    {
      "type": "deposit",
      "amount": "100.00",
      "token": "USDC",
      "timestamp": "2026-04-01T12:00:00Z"
    }
  ],
  "error": null
}

​
Query Parameters

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

​
Response Fields

​
dex
string
The DEX venue queried.
​
results
array
List of transfer records (venue-specific format).
​
error
string
Error message if the query failed. null on success.