Venue Setup

Configure trading venues using one of three setup models: Programmatic, Prepare+Confirm, or User Credentials

HyperETH supports three venue configuration models depending on each venue's native delegation capabilities.

Model 1: Programmatic Setup

Venues: Hyperliquid, HyENA

Fully automated setup using Privy agentic wallets. HyperETH generates an API wallet and registers it with the venue — no venue interaction required from the agent.

Prerequisites

Before using Model 1, you must:

Create an EVM wallet via Privy (or any EVM wallet provider)
Add HyperETH's public authentication key as a Privy signer
Set the Privy Policy to only allow Hyperliquid ApproveAgent signatures
Fund your main wallet on Hyperliquid

HyperETH Privy Configuration

When adding HyperETH as a signer on your Privy wallet, use the following configuration:

Parameter	Value
Privy App ID	`cmfqhtz3501d8jo0chcuqp2x1`
Authorization Key Quorum ID (Signer ID)	`t2mzeds46hic7sv0r9tttpxx`
Policy ID	`uxpvxsbadrlf0e9qepqslw7v`

Use these values when calling addSigners in the Privy SDK:

await addSigners({
  address: wallet.address,
  signers: [{
    signerId: 't2mzeds46hic7sv0r9tttpxx',
    policyIds: ['uxpvxsbadrlf0e9qepqslw7v'],
  }],
});

Endpoint

POST /v2/account/venues/{venue}/setup

Where {venue} is hyperliquid or hyena.

Request

{
  "privy_wallet_id": "wallet_xyz123",
  "wallet_address": "0x1234567890abcdef1234567890abcdef12345678"
}

Field	Type	Description
`privy_wallet_id`	string	Your Privy wallet ID
`wallet_address`	string	Your main wallet address

Response

{
  "venue": "hyperliquid",
  "status": "active",
  "wallet_address": "0x5555555555555555555555555555555555555555",
  "expires_at": "2026-04-17T15:30:00Z"
}

How It Works

HyperETH generates a new EVM keypair (the API wallet) and encrypts the private key for storage.

HyperETH verifies that its authentication key is registered as a signer on your Privy wallet with the correct policy.

HyperETH uses its authentication key to call the Privy API, signing an ApproveAgent transaction on your behalf. The Privy Policy Engine validates that this is an allowed operation.

HyperETH submits the signed ApproveAgent transaction to Hyperliquid, authorizing the API wallet to trade on your account.

The API wallet is registered and active. Agent wallets have trade-only permissions — they cannot withdraw or transfer funds.

Security

API wallet has trade-only permissions — cannot withdraw (enforced by Hyperliquid protocol)
Credentials auto-expire via valid_until (HyperETH renews automatically)
Revocation options: revoke HyperETH signer in Privy, or agent expires naturally

Python Example

import requests

api_key = "api_..."
headers = {
    "x-api-key": api_key,
    "Content-Type": "application/json",
}

resp = requests.post(
    "https://api.hypereth.io/v2/account/venues/hyperliquid/setup",
    headers=headers,
    json={
        "privy_wallet_id": "wallet_xyz123",
        "wallet_address": "0x1234567890abcdef1234567890abcdef12345678",
    },
)
print(resp.json())
# {"venue": "hyperliquid", "status": "active", "wallet_address": "0x...", "expires_at": "..."}

Model 2: Prepare + Confirm

Venues: AsterDex, Paradex, GRVT

A two-step process: HyperETH generates a keypair, the user registers it in the venue's web UI, then confirms the setup.

Step 1: Prepare

POST /v2/account/venues/{venue}/prepare

Where {venue} is aster, paradex, or grvt.

Request: Empty JSON body {}

Response:

{
  "venue": "aster",
  "wallet_address": "0x5555555555555555555555555555555555555555",
  "status": "pending_user_action",
  "instructions": "Go to https://www.asterdex.com/api-wallet and add 0x555... as API wallet"
}

For Paradex, the response returns public_key instead of wallet_address (Starknet keypair). For GRVT, the response returns signer_address.

Step 2: User Action

Follow the instructions in the response to register the generated address in the venue's web UI:

AsterDex: Go to the API wallet page and add the address
Paradex: Go to Account Security → Key Management → Add New Subkey
GRVT: Go to API Keys → Create → Input the signer address

Step 3: Confirm

POST /v2/account/venues/{venue}/confirm

The confirm request body varies by venue:

AsterDex

{
  "main_wallet_address": "0xYourMainWalletAddress..."
}

Paradex

{}

GRVT

GRVT requires additional credentials obtained during the UI setup:

{
  "grvt_api_key": "grvt_live_abc123def456",
  "sub_account_id": "sub_account_1"
}

Confirm Response

{
  "venue": "aster",
  "status": "active",
  "wallet_address": "0x5555555555555555555555555555555555555555"
}

Venue-Specific Details

AsterDex

Uses EVM keypair; the generated address is added as an "API wallet" in the AsterDex UI
Trading requests are signed with the API wallet private key using Keccak256 + ECDSA
Revocation: remove the API wallet in the AsterDex UI

Paradex

Uses Starknet keypair; the public key is registered as a "subkey"
Subkeys can place/cancel orders and view balances but cannot withdraw, transfer, or manage other subkeys
Revocation: remove the subkey in the Paradex UI

GRVT

Uses EVM keypair as the "signer address"
Requires a GRVT API key and sub-account ID (created in the GRVT UI alongside the signer)
Trading uses EIP-712 signing
Revocation: delete the API key in the GRVT UI

Python Example: Complete AsterDex Flow

import requests

api_key = "api_..."
headers = {
    "x-api-key": api_key,
    "Content-Type": "application/json",
}

# Step 1: Prepare
resp = requests.post(
    "https://api.hypereth.io/v2/account/venues/aster/prepare",
    headers=headers,
    json={},
)
prepare_data = resp.json()
print(f"Generated wallet: {prepare_data['wallet_address']}")
print(f"Instructions: {prepare_data['instructions']}")

# Step 2: User adds the wallet in AsterDex UI (manual step)
input("Press Enter after adding the wallet in AsterDex UI...")

# Step 3: Confirm
resp = requests.post(
    "https://api.hypereth.io/v2/account/venues/aster/confirm",
    headers=headers,
    json={"main_wallet_address": "0xYourMainWalletAddress..."},
)
print(f"Status: {resp.json()['status']}")

Model 3: User-Provided Credentials

Venues: Lighter, Kuru, Nado

Submit your venue-specific credentials directly. HyperETH encrypts them using AES-256-GCM and stores them securely.

Endpoint

POST /v2/account/venues/{venue}/credentials

Where {venue} is lighter, kuru, or nado.

Lighter

{
  "credentials": {
    "api_key_private_key": "0xdeadbeef...",
    "api_key_index": 2,
    "account_index": 0,
    "l1_address": "0x1234567890abcdef1234567890abcdef12345678"
  }
}

Field	Type	Description
`api_key_private_key`	string	Your Lighter API key private key
`api_key_index`	integer	API key index (e.g., 2)
`account_index`	integer	Account index (usually 0)
`l1_address`	string	Your L1 wallet address

Kuru

{
  "credentials": {
    "private_key": "0xdeadbeef..."
  }
}

Field	Type	Description
`private_key`	string	Your Kuru trading account private key

Nado

{
  "credentials": {
    "private_key": "0xdeadbeef...",
    "subaccount": "default"
  }
}

Field	Type	Description
`private_key`	string	Your Nado trading account private key
`subaccount`	string	Subaccount name (e.g., "default")

Response

{
  "venue": "lighter",
  "status": "active",
  "account_address": "0x1234567890abcdef1234567890abcdef12345678"
}

Credentials are encrypted before storage but you should treat them with the same care as private keys. Use environment variables or secrets vaults to manage them.

Python Example: Setup Lighter

import requests

api_key = "api_..."
headers = {
    "x-api-key": api_key,
    "Content-Type": "application/json",
}

resp = requests.post(
    "https://api.hypereth.io/v2/account/venues/lighter/credentials",
    headers=headers,
    json={
        "credentials": {
            "api_key_private_key": "0x...",
            "api_key_index": 2,
            "account_index": 0,
            "l1_address": "0x1234567890abcdef1234567890abcdef12345678",
        }
    },
)

if resp.status_code == 200:
    print(f"Lighter setup complete: {resp.json()}")
else:
    print(f"Error: {resp.status_code} — {resp.text}")

Venue Setup

On this page