API Overview#
The public docs live at:
https://www.hightop.com/docsThe public API host is:
https://api.hightop.comAgent API v1 lives under /v1/agent/*. It lets external agents execute financial actions inside a lane that a human configured in the Hightop app.
How the API Fits 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.
- Payments use the payment rail. If funds are in Earn, a payment can source from Earn as part of execution when the agent's onchain permissions allow it; an agent does not need to withdraw first just to pay an approved recipient.
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 (creating) a brand-new trusted destination
- 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, including OAuth Bearer auth.
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 notificationNot every API call broadcasts. Reads return current state. POST /v1/agent/simulate validates request shape and, by default (depth: "policy"), also runs the off-chain policy stages where applicable — evaluating owner-configured permissions when the target route has an operation type, and USD spend caps when the request's spend is deterministic (returning permission_not_granted or limit_exceeded without broadcasting). A policy stage is absent from execution_path when it was not evaluated, which is not the same as passing. If policy-layer reads fail, execution_path includes policy_read_failed; retry rather than treating would_succeed: true as a policy pass. Conversion quote creation stores a short-lived quote but does not execute a conversion.