Quickstart#
This quickstart uses header-key auth and does not require an SDK package. The public API host is:
https://api.hightop.comPrerequisites#
You need:
- a Hightop account
- a Hightop agent
- that agent's API key
API keys are shown once when generated or rotated.
Create Your First Agent#
Create and configure the agent in the Hightop app before calling the API:
- Open
AI Agents. - Choose
Create Agent, name the agent, and set its activation and expiry timing. - Give it the permissions and limits it needs for the job.
- Open the agent detail screen and generate an API key. Store it immediately; Hightop shows it once.
For service or vendor funding, prepare a recurring-payment recipient in the app and wait until it is active. Use that path instead of a withdrawal destination unless you are moving funds out to one of your own high-trust destinations.
Agents cannot create recurring-payment recipients or add brand-new trusted destinations through the public API. Those are app-only owner setup actions. Agents can pay active recurring-payment recipients and active trusted destinations inside their configured lane.
Set your credentials:
export HIGHTOP_AGENT_ID="00000000-0000-0000-0000-000000000000"
export HIGHTOP_API_KEY="hightop_agent_key"Check the Agent#
curl -sS https://api.hightop.com/v1/agent/self \
-H "x-agent-id: $HIGHTOP_AGENT_ID" \
-H "x-api-key: $HIGHTOP_API_KEY"The response includes the authenticated agent, scoped wallet addresses, the active window, and the global capability catalog. It does not return this agent's effective grants or spend caps — for those, call GET /v1/agent/self/limits, which returns the operations this agent is actually permitted to perform, its effective spend caps, and current-period usage. Read it before submitting any money movement.
If agent.active_window.starts_at is in the future, wait until that timestamp before submitting writes. If agent.active_window.expires_at is non-null, the agent stops working after that timestamp.
Get a Deposit Address#
Use the deposit-address route to fund the Hightop wallet on Base. The asset query parameter is required; Agent API v1 currently supports Base USDC for this route.
curl -sS "https://api.hightop.com/v1/agent/deposit-address?asset=USDC&chain=base" \
-H "x-agent-id: $HIGHTOP_AGENT_ID" \
-H "x-api-key: $HIGHTOP_API_KEY"Deposits land in the same Hightop wallet the agent operates. Hightop may automatically move eligible idle funds into Core Earn by default, so a freshly funded wallet can show little liquid cash while the balance appears in Earn. If funds are in Earn, use the payment endpoint directly when paying an approved recipient; do not withdraw first. The payment path can source from wallet balance and Earn when the agent's onchain permissions allow the required pre-actions.
List Balances#
curl -sS "https://api.hightop.com/v1/agent/balances?limit=50" \
-H "x-agent-id: $HIGHTOP_AGENT_ID" \
-H "x-api-key: $HIGHTOP_API_KEY"Balance amount fields are decimal asset-unit strings. For USDC, "1" means 1 USDC.
Pay a Configured Recipient#
To fund a service, call POST /v1/agent/payments. Do not call earn/withdraw or a withdrawal route first. Withdrawals are for moving funds out to your own eligible bank or crypto destinations; payments are for approved vendors, active one-off payments, and trusted destinations.
This example assumes the recipient is already configured and active in the app as a recurring-payment recipient.
curl -sS https://api.hightop.com/v1/agent/payments \
-H "content-type: application/json" \
-H "x-agent-id: $HIGHTOP_AGENT_ID" \
-H "x-api-key: $HIGHTOP_API_KEY" \
-H "Idempotency-Key: payment-$(uuidgen)" \
-d '{
"to": "recipient-id-or-handle",
"asset": "USDC",
"amount": "1",
"prefer": "auto"
}'The response returns an operation. Poll GET /v1/agent/operations/{operation_id} until it reaches a terminal status before reporting that money moved.
Simulate a Request Shape#
POST /v1/agent/simulate validates a target Agent API request shape without broadcasting and without creating durable state. Do not send an Idempotency-Key for simulation.
This example checks the shape of a conversion-quote request. Agent API amount fields are decimal asset-unit strings, so "amount": "1" means 1 unit of the from_asset.
curl -sS https://api.hightop.com/v1/agent/simulate \
-H "content-type: application/json" \
-H "x-agent-id: $HIGHTOP_AGENT_ID" \
-H "x-api-key: $HIGHTOP_API_KEY" \
-d '{
"method": "POST",
"path": "/v1/agent/conversions/quote",
"body": {
"from_asset": "USDC",
"to_asset": "ETH",
"amount": "1",
"slippage_percent": 1
}
}'slippage_percent is a number. Simulation checks the target route and request body syntax. By default (depth: "policy"), policy stages also run where they apply, returning permission_not_granted or limit_exceeded without broadcasting; routes that only create quotes or perform shape validation may omit those stages from execution_path. amount_usd and native USDC amounts can be checked against USD caps; non-USDC native amounts are not price-converted. If execution_path includes policy_read_failed, retry rather than treating would_succeed: true as a policy pass. Pass depth: "static" for shape-only validation. It does not check actual balances, quote freshness, LTV, recipient resolution, fees, or broadcast viability.
Create a Real Quote#
When you are ready to create server state, include an idempotency key. Conversion quotes expire after 60 seconds and are single-use.
Use one idempotency key per logical mutation. If the network result is unknown, retry with the same key and same body.
curl -sS https://api.hightop.com/v1/agent/conversions/quote \
-H "content-type: application/json" \
-H "x-agent-id: $HIGHTOP_AGENT_ID" \
-H "x-api-key: $HIGHTOP_API_KEY" \
-H "Idempotency-Key: quote-$(uuidgen)" \
-d '{
"from_asset": "USDC",
"to_asset": "ETH",
"amount": "1",
"slippage_percent": 1
}'Use the returned quote.quote_id with POST /v1/agent/conversions and a fresh idempotency key.
Example quote response:
{
"ok": true,
"quote": {
"quote_id": "00000000-0000-0000-0000-000000000000",
"expected_out": "0.0003",
"min_amount_out": "0.000297",
"expires_in_seconds": 60
}
}