Signing flows
Use revocable agent wallets for bots and hardware/software wallet signing for interactive apps.
Hyperliquid orders require signatures. Use a dedicated agent (API) wallet for bots and templates, or let users approve each signature in their hardware/software wallet for interactive apps.
Never put your wallet private key, seed phrase, or mnemonic in code, env files, configs, or tool arguments. Bloxwap will never ask for them.
Dedicated agent wallets for bots
Generate a dedicated Hyperliquid agent wallet for your bot, then approve its public address from your own wallet in the Bloxwap app or Hyperliquid's API-wallet page. The agent can trade on your account but cannot withdraw. Revoke its access on the same page at any time. Never use your main wallet key or seed phrase as the agent key.
The bot's HYPERLIQUID_AGENT_KEY is only the agent wallet's own generated key. HYPERLIQUID_ACCOUNT_ADDRESS is your public account address, not the agent address. Store the generated agent key in a secrets manager or local environment file excluded from source control; never log it. Approve a separate agent for each network and rotate it by approving a replacement and revoking the old agent.
import { createFastLocalWallet } from '@bloxwap/hyperliquid/signing';
import { ExchangeClient, HttpTransport } from '@bloxwap/hyperliquid';
// Only the dedicated agent's generated key belongs here.
const agentKey = process.env.HYPERLIQUID_AGENT_KEY;
const accountAddress = process.env.HYPERLIQUID_ACCOUNT_ADDRESS;
if (!agentKey || !/^0x[0-9a-fA-F]{64}$/.test(agentKey)) {
throw new Error('HYPERLIQUID_AGENT_KEY must be a generated agent key');
}
if (!accountAddress || !/^0x[0-9a-fA-F]{40}$/.test(accountAddress)) {
throw new Error('HYPERLIQUID_ACCOUNT_ADDRESS must be your public account address');
}
// Approve this agent for accountAddress before running the bot.
const agentWallet = await createFastLocalWallet(agentKey as `0x${string}`);
const client = new ExchangeClient({
transport: new HttpTransport({ isTestnet: true }),
wallet: agentWallet,
});
// Hyperliquid resolves the approved user's account from the agent signature.
await client.limitOrder({
coin: 'BTC',
isBuy: true,
sz: 0.1,
limitPx: 50000,
orderType: { limit: { tif: 'Gtc' } },
});Public MCP tools work without authentication. For authenticated MCP account reads, send a verified Privy session token as Authorization: Bearer YOUR_VERIFIED_PRIVY_SESSION_TOKEN; the requested wallet address must be controlled by that Privy user. Privy tokens expire and must be refreshed. Arbitrary API keys and argument-supplied credentials are not accepted, and MCP trade execution is currently unavailable. Never send an agent key or wallet secrets as MCP credentials or tool arguments.
Agent wallets (session keys)
Delegate trading permission from a user wallet to an automated agent without exposing the user's private key. The agent can trade but cannot withdraw, and can be revoked in the Bloxwap app or Hyperliquid's API-wallet page.
import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts';
import { createFastLocalWallet } from '@bloxwap/hyperliquid/signing';
import { ExchangeClient, HttpTransport } from '@bloxwap/hyperliquid';
// 1. Generate an agent key (one-time)
const agentKey = generatePrivateKey();
const agentAccount = privateKeyToAccount(agentKey);
// 2. User approves the agent (signed by user's wallet)
const userWallet = /* ... your user's wallet ... */;
const userClient = new ExchangeClient({
transport: new HttpTransport(),
wallet: userWallet,
});
await userClient.approveAgent({
agentAddress: agentAccount.address,
agentName: 'MyTradingBot', // optional label
});
// 3. Agent trades on behalf of user
const agentWallet = await createFastLocalWallet(agentKey);
const agentClient = new ExchangeClient({
transport: new HttpTransport(),
wallet: agentWallet,
});
// Orders are signed by agent but execute in user's account
await agentClient.limitOrder({
coin: 'ETH',
isBuy: true,
sz: 1.0,
limitPx: 3000,
orderType: { limit: { tif: 'Gtc' } },
});
// 4. User can revoke agent permission at any time
await userClient.revokeAgent({
agentAddress: agentAccount.address,
});Hardware wallets
For higher-value accounts, integrate hardware wallet signing. Bloxwap uses Ledger for on-chain settlement.
import { createWalletClient, http } from 'viem';
import { arbitrum } from 'viem/chains';
import { ExchangeClient, HttpTransport } from '@bloxwap/hyperliquid';
// Connect to Ledger (requires user interaction)
const walletClient = createWalletClient({
chain: arbitrum,
transport: http(),
});
const [address] = await walletClient.getAddresses();
// Use hardware wallet for signing
const client = new ExchangeClient({
transport: new HttpTransport(),
wallet: walletClient,
});
// Each order requires hardware confirmation
await client.limitOrder({
coin: 'SOL',
isBuy: true,
sz: 10,
limitPx: 100,
orderType: { limit: { tif: 'Gtc' } },
});Hardware wallet considerations
- Latency: Each signature requires hardware confirmation (~2-5 seconds)
- User presence: Hardware wallets require physical button presses
- Not suitable for: High-frequency trading or fully automated agents
- Best for: Manual trading with enhanced security, or infrequent rebalancing bots
Browser wallets
Integrate with MetaMask, Privy, or other injected wallets for interactive apps. Users approve each signature in their wallet; never request their wallet key or seed phrase.
import { createWalletClient, custom } from 'viem';
import { arbitrum } from 'viem/chains';
import { ExchangeClient, HttpTransport } from '@bloxwap/hyperliquid';
// Connect to browser wallet (e.g., MetaMask)
if (typeof window !== 'undefined' && window.ethereum) {
const walletClient = createWalletClient({
chain: arbitrum,
transport: custom(window.ethereum),
});
await walletClient.requestAddresses();
const [address] = await walletClient.getAddresses();
const client = new ExchangeClient({
transport: new HttpTransport(),
wallet: walletClient,
});
// User approves each transaction in browser
await client.limitOrder({
coin: 'BTC',
isBuy: false,
sz: 0.05,
limitPx: 55000,
orderType: { limit: { tif: 'Gtc' } },
});
}Testnet vs. mainnet
Always test on testnet first. Pass isTestnet: true to the transport.
// Testnet
const testnetTransport = new HttpTransport({ isTestnet: true });
// Mainnet
const mainnetTransport = new HttpTransport({ isTestnet: false });Signature warm-up
Pre-warm the signing path to reduce first-signature latency. Useful for agents that trade infrequently.
import { warmupSigning } from '@bloxwap/hyperliquid/signing';
// Use the dedicated agent key loaded above.
const wallet = await createFastLocalWallet(agentKey as `0x${string}`);
// Warm up the signing path (once at startup)
await warmupSigning(wallet);
// First signature is now fasterNext steps
- Low-latency recipes — Optimize signing performance
- Agent permissions — Risk management and scopes
- Agent templates — Reference implementations