API Overview#

The public docs live at:

https://www.hightop.com/docs

The public API host is:

https://api.hightop.com

Agent API v1 lives under /v1/agent/*. It lets external agents execute financial actions inside a lane that a human configured in the Hightop app.

The Model#

• Humans use the app to create agents, set permissions, approve paths, and monitor activity.
• Agents use the API to act inside those rules.
• Each API request resolves to one Hightop agent and one wallet.
• The agent cannot widen its own lane.
• Money-moving requests create operations that can be polled or delivered by webhook.
• Key controls are enforced by the account's onchain smart contracts.

What Agents Can Do#

Depending on the configured lane, an agent can:

• read its own balances, operations, recipients, withdrawal methods, and capabilities
• pay configured vendors or trusted destinations
• create one-off payouts
• quote and execute conversions
• move funds into and out of Earn
• borrow, repay, deleverage, and adjust collateral
• withdraw to eligible bank or crypto destinations
• manage webhook endpoints
• connect through MCP
• sign x402 payment authorizations

What Stays in the App#

Setup and authority changes stay app-only:

• creating agents
• rotating or disabling an agent's own key
• changing permissions or limits
• creating recurring recipients
• adding, confirming, cancelling, or removing trusted destinations
• cancelling active one-off payments

See App-Only Actions.

Auth Choices#

Header-key auth is for backend and first-party callers:

x-agent-id: <agent uuid>
x-api-key: <agent api key>

OAuth Bearer auth is for third-party clients:

Authorization: Bearer <jwt>

See Authentication and OAuth.

Request Lifecycle#

external agent
  -> Agent API request
  -> agent auth and scope checks
  -> request validation and idempotency
  -> agent permissions, limits, and path checks
  -> wallet execution
  -> AgentOperation
  -> polling, webhooks, Activity, or MCP notification

Not every API call broadcasts. Reads return current state. POST /v1/agent/simulate validates request shape only. Conversion quote creation stores a short-lived quote but does not execute a conversion.

Where to Start#

• Quickstart
• Authentication
• Endpoints
• Operations and Lifecycle
• Recipes