Endpoints#
Agent API v1 is the public /v1/agent/* surface. Generated OpenAPI artifacts may also include legacy agent-callable /actions/* and /info/* routes; those are not the v1 surface.
The Agent API does not expose a route to create a brand-new trusted destination; adding one is initiated in the Hightop app. Agents holding the agent:trusted_destinations:write scope can confirm, cancel, and remove trusted destinations through the routes below.
Catalog#
Agent Context#
Endpoint paths are relative to /v1/agent
| Method | Path | Description |
|---|---|---|
| GET | /self | Return the authenticated agent and scoped wallet context |
| GET | /self/limits | Return effective spend caps, operation permissions, and current-period usage |
| GET | /self/usage | Return rate-limit and usage state |
| GET | /capabilities | Return capabilities for the authenticated agent |
| GET | /capabilities.json | Return capabilities as JSON |
| GET | /openapi.json | Return the generated Agent API OpenAPI document when the feature flag is enabled |
| GET | /skill.md | Return the agent skill: a copy-paste briefing for AI agents (Prompt) |
openapi.json and skill.md are discovery artifacts (an OpenAPI document and a Markdown briefing), not JSON data endpoints, so they are intentionally outside the generated SDK/CLI/MCP references and the contract's typed-endpoint validation.
Account and Balances#
Endpoint paths are relative to /v1/agent
| Method | Path | Description |
|---|---|---|
| GET | /account | Return a scoped account summary |
| GET | /assets | List visible assets |
| GET | /protocols | List visible protocols |
| GET | /balances | List balances |
| GET | /balances/cash | List cash balances |
| GET | /activity | List scoped Activity rows without marking them read |
Operations#
Endpoint paths are relative to /v1/agent
| Method | Path | Description |
|---|---|---|
| GET | /operations | List AgentOperation rows |
| GET | /operations/{id} | Get one AgentOperation |
| POST | /simulate | Validate a write request — shape plus, where applicable, owner permissions and spend caps — without broadcasting |
Recipients and Payments#
Endpoint paths are relative to /v1/agent
| Method | Path | Description |
|---|---|---|
| GET | /recipients | List recurring-payment and one-off-payment recipients |
| GET | /recipients/{id} | Get one recipient |
| POST | /recipients/resolve | Resolve an agent-facing recipient identifier |
| GET | /recurring-payments | List recurring payment recipients |
| GET | /recurring-payments/{id} | Get one recurring payment recipient |
| GET | /trusted-destinations | List trusted destinations |
| GET | /trusted-destinations/{id} | Get one trusted destination |
| POST | /trusted-destinations/{id}/confirm | Confirm a pending trusted destination |
| POST | /trusted-destinations/{id}/cancel | Cancel a pending trusted destination |
| DELETE | /trusted-destinations/{id} | Remove a trusted destination |
| GET | /payments | List payment operations |
| GET | /payments/{id} | Get one payment operation |
| POST | /payments | Create a payment operation |
| GET | /one-off-payments | List one-off payment operations |
| GET | /one-off-payments/{id} | Get one one-off payment operation |
| POST | /one-off-payments | Create a one-off payment operation |
Transfers and Methods#
Endpoint paths are relative to /v1/agent
| Method | Path | Description |
|---|---|---|
| GET | /withdrawal-methods | List withdrawal methods |
| GET | /deposit-methods | List deposit methods |
| GET | /deposit-address | Return a Base deposit address |
| GET | /withdrawals | List withdrawal operations |
| GET | /withdrawals/{id} | Get one withdrawal operation |
| POST | /withdrawals/to-bank | Create a bank withdrawal operation |
| POST | /withdrawals/to-crypto | Create a crypto withdrawal operation |
Earn, Borrow, and Conversion#
Endpoint paths are relative to /v1/agent
| Method | Path | Description |
|---|---|---|
| GET | /earn | List earn positions |
| GET | /earn/{id} | Get one earn position |
| GET | /earn/opportunities | List earn opportunities |
| POST | /earn/deposit | Create an earn deposit operation |
| POST | /earn/withdraw | Create an earn withdrawal operation |
| POST | /earn/move | Create an earn move operation |
| POST | /earn/rewards/claim | Create a rewards claim operation |
| GET | /borrow | Return borrow summary |
| POST | /borrow | Create a borrow operation |
| GET | /borrow/collateral | List collateral |
| POST | /borrow/repay | Create a debt repayment operation |
| POST | /borrow/deleverage | Create a target-LTV deleverage operation |
| POST | /borrow/collateral/add | Create a collateral add operation |
| POST | /borrow/collateral/remove | Create a collateral remove operation |
| POST | /conversions/quote | Create a stateful conversion quote |
| GET | /conversions | List conversion operations |
| GET | /conversions/{id} | Get one conversion operation |
| POST | /conversions | Execute a conversion from a quote |
x402 Payments#
Endpoint paths are relative to /v1/agent
| Method | Path | Description |
|---|---|---|
| POST | /x402/quote | Quote an x402 resource without creating state (agent:simulate) |
| POST | /x402/sign | Sign an x402 payment authorization (agent:payments:write) |
| POST | /x402/purchase | Sign and complete an x402 purchase (agent:payments:write) |
See x402 Payments and the Pay with x402 recipe.
Webhooks#
Endpoint paths are relative to /v1/agent
| Method | Path | Description |
|---|---|---|
| GET | /webhooks | List webhook endpoints |
| POST | /webhooks | Create a webhook endpoint |
| GET | /webhooks/{id} | Get one webhook endpoint |
| PATCH | /webhooks/{id} | Update a webhook endpoint |
| DELETE | /webhooks/{id} | Delete or disable a webhook endpoint |
| POST | /webhooks/{id}/rotate-secret | Rotate a webhook signing secret |
| GET | /webhooks/{id}/deliveries | List webhook delivery attempts |
| POST | /webhooks/{id}/test | Send a webhook.test delivery |