CLI#

@hightop/cli is the official command-line interface for the Agent API. The executable is hightop. It uses @hightop/sdk under the hood and derives its command coverage from the generated Agent API endpoint catalog, so every /v1/agent/* endpoint is reachable as a command.

Reach for the CLI for scripting, cron jobs, CI steps, and quick one-off operations from a shell. For TypeScript services use the SDK; for AI clients use MCP. See Choose Your Surface for the comparison. The full command listing is in the CLI Command Reference.

Install#

npm install -g @hightop/cli

This puts hightop on your PATH. The CLI targets Node 20 or newer.

Configure#

Set a base URL and exactly one auth mode. The CLI reads credentials from environment variables.

Header-key auth:

export HIGHTOP_BASE_URL=https://api.hightop.com
export HIGHTOP_AGENT_ID=...
export HIGHTOP_API_KEY=...

Bearer-token auth:

export HIGHTOP_BASE_URL=https://api.hightop.com
export HIGHTOP_BEARER_TOKEN=...

Supported environment variables:

HIGHTOP_BASE_URL
HIGHTOP_AGENT_ID
HIGHTOP_API_KEY
HIGHTOP_BEARER_TOKEN
HIGHTOP_TIMEOUT_MS

Every variable has an equivalent flag for local or debug use:

hightop self --base-url https://api.hightop.com --agent-id ... --api-key ...

The CLI does not auto-load .env files. For local testing, source one into your shell:

set -a
source .env.agent
set +a

Discover commands#

The CLI is self-documenting. Use --help at any level:

hightop --help                       # global help and command groups
hightop borrow collateral --help     # a command group
hightop one-off-payments create --help   # a single endpoint command

Run commands#

hightop self --pretty
hightop balances --pretty
hightop operations get <operation-id> --include onchain --pretty
hightop webhooks create --url https://example.com/hook --event-types payment.executed,webhook.test --pretty
hightop x402 quote --url https://example.com/paid-resource --pretty

--pretty formats JSON output for humans; omit it for compact, pipe-friendly JSON.

Flags#

Flags are generated from each endpoint's query and body fields by converting underscores to dashes — amount_usd becomes --amount-usd. Booleans are detected from the schema, so a boolean field becomes a bare --flag.

Array fields accept repeated or comma-separated values:

hightop webhooks create --url https://example.com/hook --event-types payment.executed,webhook.test
hightop earn rewards claim --protocols underscore-earn --protocols ripe-rewards

For complex or deeply nested bodies, pass raw JSON with --body:

# amount is a USDC base-unit integer string (6 decimals): "1000000" = 1 USDC
hightop x402 sign --body '{"pay_to":"0x...","amount":"1000000","target_url":"https://example.com"}'

Writes: idempotency, simulate, wait#

Mutating commands generate an idempotency key automatically unless you pass --idempotency-key. The key is printed in the JSON response so you can deliberately retry the same logical operation:

hightop one-off-payments create --to 0x... --asset USDC --amount-usd 25 --pretty

Use --simulate to validate a request shape against /v1/agent/simulate instead of broadcasting. Simulate is available on the write commands the API marks as simulatable:

hightop borrow repay --asset GREEN --amount-usd 25 --simulate --pretty

Use --wait to poll the returned operation until it reaches a terminal state, with --wait-timeout-ms to bound the wait:

hightop conversions execute --quote-id <quote-id> --wait --pretty

Escape hatches#

hightop raw calls any known /v1/agent/* route directly. The openapi command is public and runs without auth (it still needs HIGHTOP_BASE_URL or --base-url); capabilities requires auth (agent:read):

hightop raw GET /v1/agent/openapi.json --pretty
hightop openapi --pretty          # public, no auth
hightop capabilities json --pretty  # requires agent auth

Output and exit codes#

Successful commands print the JSON response to stdout and exit 0. Failed requests print the normalized Agent API error and exit non-zero, so you can branch on exit status in scripts. Combine with --pretty for debugging and plain output for piping into jq.

Next#

• CLI Command Reference — every command and flag, generated from the contract
• Choose Your Surface — CLI vs SDK vs MCP vs raw HTTP
• Going to Production — idempotency, retries, and error handling
• Authentication — header-key and OAuth