Trading & Payments

aibank integrates with Hyperliquid for perpetual futures trading and implements the x402 protocol for HTTP-native payments.

Hyperliquid Trading

All Hyperliquid operations go through a single action-based endpoint:

POST /v1/trading/hyperliquid

Read-only actions (info)

These query Hyperliquid's data without requiring signatures:

// Get account status
const status = await fetch("http://localhost:4000/v1/trading/hyperliquid", {
  method: "POST",
  headers: {
    "X-API-Key": "ak_your_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    walletId: "wallet-uuid",
    action: "status",
  }),
});

Available info actions

Action	Description	Extra parameters
`status`	Full account state	--
`positions`	Open positions	--
`orders`	Open orders	--
`fills`	Recent fills	--
`markets`	Market metadata	--
`ticker`	Mid prices	`symbol` (optional)
`orderbook`	L2 order book	`symbol` (default: ETH)
`funding`	Funding rates	--

Examples

// Get all mid-prices
const tickers = await tradeRequest({
  walletId: "wallet-uuid",
  action: "ticker",
});

// Get ETH orderbook
const book = await tradeRequest({
  walletId: "wallet-uuid",
  action: "orderbook",
  symbol: "ETH",
});

// Get positions
const positions = await tradeRequest({
  walletId: "wallet-uuid",
  action: "positions",
});

Exchange actions (write)

These actions modify state and require EIP-712 typed signatures. They are currently documented but return 501 Not Implemented with the payload that would be sent:

Action	Description	Parameters
`order`	Place a limit order	`symbol`, `side`, `price`, `amount`, `tif`
`cancel`	Cancel an order	`symbol`, `orderId`
`cancel_all`	Cancel all orders	`symbol` (optional)
`set_leverage`	Set leverage	`symbol`, `leverage`, `cross`
`withdraw`	Withdraw from Hyperliquid	`amount`, `destination`
`transfer`	Internal USD transfer	`amount`, `destination`

Order example

const res = await fetch("http://localhost:4000/v1/trading/hyperliquid", {
  method: "POST",
  headers: {
    "X-API-Key": "ak_your_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    walletId: "wallet-uuid",
    action: "order",
    symbol: "ETH",
    side: "buy",
    price: "3000.00",
    amount: "0.1",
    tif: "Gtc",
  }),
});

Spending controls are enforced on exchange actions -- if the amount exceeds the wallet's per-transaction or daily limit, the request is rejected with a 403.

x402 Payments

x402 is the HTTP-native payment protocol. Instead of using API keys, agents pay per-request using on-chain USDC transfers.

How it works

Agent sends a request without an X-API-Key header
Server returns 402 Payment Required with payment instructions in headers
Agent sends USDC to the specified address on the specified chain
Agent retries the request with X-Payment: <txHash> header
Server verifies the on-chain payment and processes the request

402 response headers

Header	Description
`X-Payment-Required`	`true`
`X-Payment-Amount`	Amount in USDC (e.g. `"0.01"`)
`X-Payment-Currency`	`USDC`
`X-Payment-Recipient`	Recipient address
`X-Payment-Chain`	Chain to pay on (e.g. `base-sepolia`)
`X-Payment-Description`	What the payment is for

Manual x402 flow

// Step 1: Make request without API key
const res = await fetch("http://localhost:4000/v1/gateway/anthropic/v1/messages", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ model: "claude-sonnet-4-20250514", max_tokens: 100, messages: [] }),
});

// Step 2: res.status === 402, read payment details
const payment = await res.json();
// payment.payment.amount = "0.01"
// payment.payment.recipient = "0x..."
// payment.payment.chain = "base-sepolia"

// Step 3: Send USDC on-chain (using your wallet)
const txHash = "0xabc123...";

// Step 4: Retry with proof
const result = await fetch("http://localhost:4000/v1/gateway/anthropic/v1/messages", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Payment": txHash,
    "X-Payment-Chain": "base-sepolia",
  },
  body: JSON.stringify({ model: "claude-sonnet-4-20250514", max_tokens: 100, messages: [] }),
});

Automatic x402 with the SDK

The SDK handles the entire flow automatically:

const wallet = aibank.getWallet("wallet-uuid");

// This automatically pays 402 challenges
const response = await wallet.x402Fetch(
  "http://localhost:4000/v1/gateway/anthropic/v1/messages",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      model: "claude-sonnet-4-20250514",
      max_tokens: 100,
      messages: [{ role: "user", content: "Hello" }],
    }),
  }
);

const data = await response.json();

Security

Double-spend protection: Each transaction hash can only be used once
On-chain verification: Payments are verified against the blockchain
Amount validation: Payment must meet or exceed the required amount
Recipient validation: Payment must be sent to the correct address

Trading & Payments

On this page