@hightop/cli

Command-line interface for the Hightop Agent API.

The executable is hightop. The CLI uses @hightop/sdk for all Agent API requests and derives normal command coverage from the generated Agent API endpoint catalog.

Configuration

Set a base URL and one auth mode for protected commands.

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

Equivalent flags are available for local/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 the shell:

cp packages/cli/.env.example .env.agent
# edit .env.agent with real credentials
set -a
source .env.agent
set +a

Help

Global help:

hightop --help

Command-group help:

hightop x402 --help
hightop borrow collateral --help

Endpoint command help:

hightop one-off-payments create --help
hightop webhooks update --help

When running from a checkout before publishing, call the built file directly:

node packages/cli/dist/index.js x402 --help

Commands

Examples:

hightop self --pretty
hightop balances --pretty
hightop operations get <operation-id> --include-onchain --pretty
hightop borrow repay --asset GREEN --amount-usd 25 --simulate --pretty
hightop one-off-payments create --to 0x... --asset USDC --amount-usd 25 --simulate --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
hightop raw GET /v1/agent/openapi.json --pretty

The generated command layer supports all catalogued /v1/agent/* endpoints. CLI flags are generated from endpoint query/body field names by converting underscores to dashes, for example amount_usd becomes --amount-usd.

For complex bodies, pass a JSON object:

hightop x402 sign --body '{"pay_to":"0x...","amount":"1000","target_url":"https://example.com"}'

Repeated or comma-separated array flags are accepted for known array fields:

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

Writes

For mutating commands, the CLI generates an idempotency key unless --idempotency-key is provided. The key is printed in the JSON response so callers can retry the same logical operation intentionally.

Use --simulate to call /v1/agent/simulate instead of broadcasting:

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

Use --wait to poll the returned operation until it reaches a terminal state:

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

Public openapi and capabilities json commands can run without auth, but still require HIGHTOP_BASE_URL or --base-url.