How to Connect a Hyperliquid API Wallet to Ninja Terminal

Hyperliquid has no API key and secret. Instead, you approve an API wallet (also called an agent wallet) that signs orders for your account. Ninja Terminal connects this way. See also Hyperliquid on Ninja Terminal.

What is an API wallet, and why use one?

An API wallet is a separate key pair. Your main wallet approves it once, and after that it can sign trading actions for your account. Hyperliquid’s documentation states that API wallets are only used to sign, and that data queries use the actual master or sub-account address, not the agent address.

For a trader, the result is simple:

• Your main wallet’s private key never goes into a trading tool.
• Ninja Terminal’s in-app guide states that the API wallet can trade without withdrawal permission.
• You can approve a different API wallet for each tool, and replace one without touching the others.

Hyperliquid also advises against reusing agent addresses and recommends one API wallet per trading process. It allows one unnamed approved wallet and up to three named ones per account.

How do you create and approve the API wallet?

Ninja Terminal’s setup walks through these steps. The labels come from the Hyperliquid API page and can change.

1. Open the Hyperliquid API page and connect your trading wallet.
2. Enter a name for the API wallet, such as “Ninja Terminal”.
3. Select Generate. This creates a new API wallet address. It belongs to the API wallet, not to your trading account.
4. Select Authorize API Wallet.
5. Save the private key shown, in a password manager.
6. Choose how long the API wallet stays valid. Hyperliquid caps this at 180 days.
7. Authorize, then confirm in your wallet.
8. Copy your trading wallet’s public address from your main wallet. You need it next.

What does Ninja Terminal ask for?

The Add Account form for Hyperliquid has two required fields:

Field	What to enter
API Wallet Private Key	The private key of the API wallet (64 hexadecimal characters, optionally starting with 0x)
Wallet Address	Your trading wallet address, not the API wallet address
Nickname (optional)	Any label you like

There is no API secret, no passphrase, and no IP allowlist step for Hyperliquid. The IP list shown for Binance, OKX, and Bybit is not part of the Hyperliquid setup.

How does Ninja Terminal check the credentials?

When you select Test or Connect, Ninja Terminal checks on Hyperliquid that the private key belongs to an active API wallet and that this wallet is authorized for the address you entered. It rejects:

• a main wallet private key (“Main wallet private keys are not accepted”);
• an API wallet that is not active;
• an API wallet that is approved for a different wallet address;
• a wallet address pasted in the private key field.

Ninja Terminal encrypts the private key with AES-256-GCM and stores it on your device. Orders are signed on your device and sent to Hyperliquid. Funds stay in your own account. After connecting, you can trade Hyperliquid perpetuals and spot, plus HIP-3 builder markets, from the same workspace.

What should you do when the API wallet expires or you want to rotate it?

Authorize a new API wallet on the Hyperliquid API page, then connect it in Ninja Terminal. Do not reuse the old agent address: Hyperliquid warns that after a wallet is deregistered, its nonce state can be pruned, which makes replay of earlier signed actions possible. Remove old wallets you no longer use.

For a broader routine, see the API key security checklist.

What if the connection fails?

• “API wallet is not active”: the wallet was not authorized, or it expired. Authorize it again.
• “Not authorized for the supplied wallet address”: you entered the wrong trading wallet address. Use the account address that approved the wallet.
• Private key error: the key must be 32 bytes, or 64 hexadecimal characters.