Quickstart: from a key to a fill in five minutes

1. Create a key

Open Settings → API Keys. Name the key, grant read and trade, and set the caps you can live with. A new key starts read-only at $50 per call and $200 per day; raise it in the dialog.

Copy the secret once. It is shown only at creation. Export it in your shell:

export PB_KEY=pb_…

2. Read the account

curl -s https://protocolbanks.com/api/v1/agent/state \
  -H "Authorization: Bearer $PB_KEY"

A fresh wallet gets a paper account ($500 simulated) with real Hyperliquid market data. The response includes mode, equity, positions, activity and the key's policy with spentTodayUsd.

3. Place an order

curl -s https://protocolbanks.com/api/v1/agent/orders \
  -H "Authorization: Bearer $PB_KEY" -H "Content-Type: application/json" \
  -d '{"coin":"BTC","side":"long","sizeUsd":20}'

On success the response carries the fill, the fee and remainingTodayUsd. Ask for more than the key's per-call cap and the server answers 403 before the agent is touched:

{"ok":false,"error":"order of $5000.00 exceeds this key's per-call cap of $100"}

4. Create an invoice

curl -s https://protocolbanks.com/api/v1/agent/invoice \
  -H "Authorization: Bearer $PB_KEY" -H "Content-Type: application/json" \
  -d '{"to":"0xabc…","amount":25,"description":"agent work"}'

The invoice is created pending and returns a paymentLink (/pay?invoice=…&sig=…). Give the link to the payer; read settlement back with GET /api/invoice?id=…&sig=….

5. Use the SDK or one command

import { ProtocolBanks } from "@everestan/protocolbanks-sdk"

const pb = new ProtocolBanks({ apiKey: process.env.PB_KEY! })
const state = await pb.agent.state()
const order = await pb.agent.order({ coin: "BTC", side: "long", sizeUsd: 20 })
if (!order.ok) console.log(order.status, order.error) // 403 / 409 are returned

If you have repository access, PB_KEY=pb_… pnpm example:agent (add --invoice) walks the same flow. The tool manifest for agent frameworks is @everestan/protocolbanks-agent-tools.

6. Going live

Approve an agent wallet on Hyperliquid from the cockpit's Go Live card. The same endpoints switch to live mode (mode: "live"); the wallet has trading-only permissions. Start with a budget you are willing to lose.