Skip to content
Hightop docs header art
Hightop
API and Integrations

API Overview#

Your agents need a way to execute financial actions — pay vendors, move capital, manage yield, or handle borrowing flows — without raw wallet access. The Hightop API is that execution layer.

The app is where humans define the lane. The API is how external agents operate inside it.

The Mental Model#

  • The app and the API connect to the same Hightop account.
  • The account has one shared pool of capital across payments, yield, borrowing, and rebalancing.
  • A Hightop agent is the control profile attached to your external agent or workflow.
  • An API key authenticates that external agent to the lane you configured for it.
  • Every API request is evaluated against the same rules the app shows you.
  • Key rules are enforced by the account's onchain smart contracts, not just by Hightop's servers.

What the API Is For#

Depending on the lane you configure, an external agent can use the API to initiate actions like:

  • paying approved vendors
  • creating or executing one-off payouts
  • using active trusted destinations
  • moving balances into and out of Earn
  • rebalancing between supported assets and positions
  • managing supported borrowing actions

How the App and API Work Together#

The app and the API have different jobs:

  • In the app, you create agents, set permissions, approve payment paths, and define limits.
  • In the API, your external agents request actions inside those rules.
  • In the app, you monitor activity, receive alerts, and revoke or adjust access when needed.

The API is for action execution inside a configured lane. Rule changes — creating agents, adjusting permissions, approving vendors, adding trusted destinations — happen in the app through the control wallet, not through the API.

How a Request Is Evaluated#

Quick example: your operations agent sends a request to pay an approved compute vendor $200 in USDC. Hightop identifies the lane from the API key, checks that the agent is active, confirms it has permission to use the recurring-payment path, verifies that the vendor is approved, checks that $200 fits the configured limits, and then executes the payment.

Underneath that example, each request follows the same pattern:

  1. The external agent authenticates with its Hightop agent API key.
  2. Hightop identifies which lane that key belongs to.
  3. The system checks whether the agent is active and whether the request fits its permissions.
  4. The system checks the relevant rule layers: account-wide rules, agent-specific rules, and any path-specific rules.
  5. If the request fits the rules, the wallet assembles and executes the action through the appropriate path or protocol.
  6. If the request does not fit the rules, it is blocked before funds move.

That same logic applies whether the action is a payment, an Earn move, a rebalance, or a borrowing action.

Common Outcomes#

From a builder's point of view, an API request usually lands in one of three buckets:

It Executes#

The request fits the configured lane, the wallet can assemble the action, and funds move.

It Enters a Waiting State#

Some successful requests create an object that still has to wait before it can complete. The clearest example today is a one-off payout above the configured instant threshold: the creation request succeeds, but the payout then sits behind its review delay before it becomes claimable or executable.

Waiting states also exist elsewhere in Hightop, like new agents or new trusted destinations, but those are configuration changes managed in the app rather than API-side action execution.

It Is Blocked#

If the request falls outside the lane, Hightop blocks it before funds move.

Common causes include:

  • the agent is not active yet
  • the agent lacks the required permission
  • a transaction, period, or lifetime limit was hit
  • a cooldown still applies
  • the asset or venue is not allowed
  • the payment path or destination is not approved

This is not a generic failure mode. It is the control system doing its job. For the debugging flow, see If an Agent Goes Off-Script.

Where to Go Next#

Previous

Build on Hightop

Next

Emerging Payment Protocols