Onboarding

Before a managed account can trade, its master wallet approves API trading on Hyperliquid. You do this once, and it takes a couple of minutes.

The master wallet is the Hyperliquid account your API key is bound to. It must have deposited on Hyperliquid first.

Onboard on Markets

1. Open markets.xyz/api-access.
2. Connect your master wallet.
3. Select Create API key and sign the message. This creates your account and shows your key once. If you already have a key, choose Use it instead and paste it; the connected wallet must be the one it's bound to.
4. Select Approve and sign the two requests your wallet shows: the trading agent, then the builder fee.

What each signature does

Approve trading agent

The API generates a new trading agent for your account and keeps its key encrypted. Your master wallet signs Hyperliquid's ApproveAgent action, authorising that agent to trade on the account's behalf. It appears on Hyperliquid as an API wallet named kinetiq.

The agent can place, modify and cancel orders and change leverage. It can never withdraw or transfer funds; Hyperliquid does not give agents that permission.

Approve builder fee

Your master wallet signs Hyperliquid's ApproveBuilderFee action, allowing Markets to charge its builder fee on your orders. Hyperliquid rejects any order carrying a builder fee the account hasn't approved, so trading can't start without it.

You approve the highest fee your account can be charged: the top of the volume tiers. The fee actually charged is often lower and only falls from there as your volume grows. See Fees.

Unified account

Once the agent is approved, an account in Hyperliquid's default mode is switched to unified account mode, so one balance margins the main perpetuals, every HIP-3 market and spot. You don't sign anything for this, and trading doesn't depend on it. See HIP-3 markets.

Checking status

GET /v1/managed-agent shows the agent and the account mode:

curl -s https://hl-api-production-65c8.up.railway.app/v1/managed-agent -H "Authorization: Bearer $API_KEY"

{
  "agent": {
    "agent_address": "0x31c7…cd02",
    "approved": true,
    "approved_at": "2026-09-29T17:51:02.004Z",
    "created_at": "2026-09-29T17:50:39.911Z"
  },
  "account_mode": "unifiedAccount"
}

agent is null until one is created.

GET /v1/account/status is the full checklist, read live from Hyperliquid:

curl -s https://hl-api-production-65c8.up.railway.app/v1/account/status -H "Authorization: Bearer $API_KEY"

{
  "ready_to_trade": true,
  "signers": {
    "master": "0x2289fc466745c0fc5e38a6fc63ededdf9e04e56f",
    "approved_agents": [
      {
        "address": "0x31c7…cd02",
        "name": "kinetiq",
        "validUntil": 1793085105693
      }
    ]
  },
  "builder_fee": {
    "required_tenths_bps": 50,
    "approved_tenths_bps": 50,
    "ok": true
  },
  "account_mode": "unifiedAccount",
  "hip3_collateral_shared": true
}

Trading works once ready_to_trade is true. Until then, trading requests return 412 with the code precondition_failed.

Replacing the agent

Onboarding again creates a new agent and replaces the old one: the API stops using the old agent immediately, and trading resumes once your master wallet approves the new one. Do this if you believe the agent was compromised, or after revoking it.

Revoking the agent

You can cut off all trading at any time, without contacting us, by removing the kinetiq API wallet on Hyperliquid (the API page of the Hyperliquid app). Every trading request then fails until you onboard again.

Scripted onboarding

If you'd rather not use a browser, sign-up and both approvals can be done from a script: the API returns each one as EIP-712 typed data for your master wallet to sign.

1. POST /v1/sign-up/challenge with {"address": "0x…", "chain_id": 42161} returns a one-time message. Sign its typed_data with the master wallet and send {"nonce", "chain_id", "signature"} to POST /v1/sign-up: the answer holds your API key. The message is valid for 5 minutes and works once.
2. POST /v1/managed-agent creates the agent and returns approve_agent, a prepared action.
3. Sign approve_agent.typed_data with the master wallet and send the signature to POST /v1/actions/{id}/submit, where id is approve_agent.id.
4. POST /v1/builder-fee/approve returns the builder fee approval. Sign and submit it the same way.

We can share a Python example client that does all of it in one command:

pip install -r requirements.txt
export HLAPI_URL=https://hl-api-production-65c8.up.railway.app
HL_MASTER_KEY=0x... python hlapi_client.py sign-up        # prints your API key
export HLAPI_API_KEY=hlk_...
HL_MASTER_KEY=0x... python hlapi_client.py onboard-managed

Keep the master key out of your trading systems: run this once from a secure machine, or sign with a hardware wallet or key management service instead. Client-signed accounts shows how to sign typed data in Python and TypeScript.