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.
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, permissions, limits, and current usage.
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.
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. It does not check balances, permissions, quote freshness, LTV, recipient policy, 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
}
}