Hyperliquid API Wallet Guide: Read-Only Checks and SDK Examples

Published: May 14, 2026 | Updated: June 16, 2026 | Reading time: 15 minutes | Author: Carlos Vendrell

When the Hyperliquid frontend refuses a wallet, users often search for an API withdrawal guide. The practical question is not “can the API fix it?” The practical question is “what does the account look like right now?”

This guide gives concrete checks for that first pass: account address, agent/API wallet, visible balances, open positions, destination address, fees, and verification records. The examples use public account addresses only. They do not include signed withdrawal code.

Why API Paths Matter

A high-risk address warning usually appears in the browser interface. If that interface refuses connection or actions, API review becomes useful because it can answer a narrower question: what balances, positions, orders, and agent wallets are visible for the account?

For background on the warning itself, start with the Hyperliquid flagged address guide. For withdrawal-specific trade-offs, see the Hyperliquid withdrawal options page. If the case becomes a broader stuck-asset review, compare it with the smart contract recovery boundary guide and organize public evidence with the block explorer fund-tracking workflow.

Frontend Restriction vs API Execution

The frontend is the browser app. The API is used for data requests and protocol-related actions. A frontend block can stop normal browser use while still leaving account-state questions open.

Start with facts: current balances, open positions, lock windows, fee availability, destination address, and how any future transaction would be checked. If those facts are not known, stay with read-only queries.

Master Account vs Agent Wallet

Many API mistakes come from mixing up the user account, sub-account, destination address, and agent/API wallet. Inventory the address that actually holds the Hyperliquid account state first. Treat an agent wallet as a permissioned signer, not as the account balance and not as the withdrawal destination.

If Hyperliquid returns an error such as cannot use existing user address as agent, pause and review the signing setup. That message usually points to an agent-wallet configuration problem, not to the balances themselves.

Required Prerequisites

Before any API-path work is considered, make the case readable. At minimum, note the public wallet, visible balances, asset categories, open positions, destination address, fee model, and expected verification method.

The first pass can use public data and read-only evidence. Keep signing questions separate until the account inventory and destination are clear.

Read-Only Checks First

Run read-only checks before arguing about the final path. They tell you whether the case is spot-only, has open perps, contains vault balances, has pending withdrawals, or has API wallet confusion.

Use the same public account address through the first pass. If the account has sub-accounts, query the master address first, then query each sub-account separately after you identify it.

Curl Account-State Examples

The official Hyperliquid info endpoint accepts read-only JSON requests. Replace 0xYOUR_ACCOUNT_ADDRESS with the public account address being reviewed. These commands do not sign transactions and do not approve withdrawals.

Use this first when the account may have open perps or withdrawable perp margin:

curl -s https://api.hyperliquid.xyz/info \
  -H "Content-Type: application/json" \
  -d '{"type":"clearinghouseState","user":"0xYOUR_ACCOUNT_ADDRESS"}'

Then check spot balances separately. Do not assume one browser balance is the whole account:

curl -s https://api.hyperliquid.xyz/info \
  -H "Content-Type: application/json" \
  -d '{"type":"spotClearinghouseState","user":"0xYOUR_ACCOUNT_ADDRESS"}'

Open orders matter because the account can keep changing while the frontend issue is being reviewed:

curl -s https://api.hyperliquid.xyz/info \
  -H "Content-Type: application/json" \
  -d '{"type":"openOrders","user":"0xYOUR_ACCOUNT_ADDRESS"}'

Recent fills help reconstruct whether the account was actively trading before the warning appeared:

curl -s https://api.hyperliquid.xyz/info \
  -H "Content-Type: application/json" \
  -d '{"type":"userFills","user":"0xYOUR_ACCOUNT_ADDRESS"}'

Check API agents when the issue involves an API wallet, agent setup, or an error such as cannot use existing user address as agent:

curl -s https://api.hyperliquid.xyz/info \
  -H "Content-Type: application/json" \
  -d '{"type":"apiAgents","user":"0xYOUR_ACCOUNT_ADDRESS"}'

Rust hypersdk Examples

For Rust users, the community hypersdk package from Infinite Field wraps Hyperliquid HTTP and WebSocket APIs. The examples below are intentionally read-only. They use hypercore::mainnet(), parse a public address, and call documented query methods such as clearinghouse_state, user_balances, open_orders, and api_agents.

Minimal Cargo.toml dependencies:

[dependencies]
hypersdk = "0.2"
tokio = { version = "1", features = ["full"] }
anyhow = "1"

Inventory perps, spot balances, open orders, and API agents without signing anything:

use hypersdk::hypercore;
use hypersdk::Address;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let client = hypercore::mainnet();
    let user: Address = "0xYOUR_ACCOUNT_ADDRESS".parse()?;

    let perps = client.clearinghouse_state(user, None).await?;
    println!("account_value={}", perps.margin_summary.account_value);
    println!("withdrawable={}", perps.withdrawable);
    for asset_position in &perps.asset_positions {
        let position = &asset_position.position;
        println!("position {} size={} entry={:?} pnl={}", position.coin, position.szi, position.entry_px, position.unrealized_pnl);
    }

    let spot_balances = client.user_balances(user).await?;
    for balance in &spot_balances {
        println!("spot {} total={} held={}", balance.coin, balance.total, balance.hold);
    }

    let orders = client.open_orders(user, None).await?;
    println!("open_orders={}", orders.len());

    let agents = client.api_agents(user).await?;
    for agent in &agents {
        println!("agent {} {:?} valid_until={:?}", agent.name, agent.address, agent.valid_until);
    }

    Ok(())
}

If the address role is unclear, query the role before interpreting agent-wallet errors:

use hypersdk::hypercore;
use hypersdk::Address;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let client = hypercore::mainnet();
    let address: Address = "0xADDRESS_TO_CLASSIFY".parse()?;

    let role = client.user_role(address).await?;
    println!("role={role:?}");

    Ok(())
}

These examples are useful for diagnosis, not execution. If the next step would require a signer, an exchange action, or any request that changes account state, stop and document the expected token, amount, destination, network, fee, nonce handling, and failure mode before any transaction is considered.

How to Read the Output

Common Account States

A spot-only account is simpler than an account with active perps, but it still requires fee and destination checks. An account with open perps may require position management before any final withdrawal can be reconciled. Vault assets, staking positions, or locked balances may have timing rules that cannot be skipped by changing interfaces.

Mixed balances are common. In a mixed account, a reviewer should separate each category and avoid treating the account as a single withdrawable number. This was one lesson from the anonymized Hyperliquid incident review, where accounting categories had to be separated before the final receipt could be understood.

Security Boundaries

Every future transaction should be checked by token, amount, destination, network, fee, and timestamp. Use small test actions only when the account state supports that approach and the destination is confirmed.

Keep logs. A useful review should show which read-only calls were run, what they returned, what assumptions remain, and what failure cases still exist. If those notes are unclear, stay at the read-only stage.

When Not to Attempt Manual API Work

Do not attempt manual API work if you cannot read the relevant documentation, interpret error responses, verify transaction construction, or explain the account state. Stop if the destination address is uncertain, if open positions are not understood, or if the action cannot be described before execution.

If you need structured review, use the case evaluation page to request a technical review after the account-state notes are ready.

FAQ

Conclusion

Hyperliquid API withdrawal planning starts with read-only checks. Identify the account address, separate the agent/API wallet, confirm balances, open positions, orders, and agents, then decide whether support, manual API review, or withdrawal-options comparison is the right next step.

About the Author: Carlos Vendrell

DeFi Recovery Specialist

Carlos focuses on incident response, contract-level recovery execution, and security-first workflows for restricted-account scenarios.

Twitter/XLinkedInMedium

Last updated: June 16, 2026

← Back to Blog