Developer Tools#

There are four ways to reach the Agent API. They all speak to the same /v1/agent/* surface, enforce the same permissions and limits, and return the same operations and errors. Pick the one that fits how you build.

Choose your surface#

Surface	Best for	Language	Auth	You manage
TypeScript SDK	Agents and services in TS/JS	TypeScript / JavaScript	Header-key or bearer	Almost nothing — typed calls, idempotency, polling, errors handled
CLI	Scripts, cron, CI, one-off ops	Any (shell)	Header-key or bearer	Flags and env vars; idempotency and polling are built in
MCP	AI clients (Claude and other MCP hosts)	n/a (tool calls)	OAuth bearer (or header-key for native/server clients)	A connector and OAuth consent
Raw HTTP	Any other language or runtime	Any	Header-key or bearer	Headers, idempotency keys, operation polling, retries

Rules of thumb:

Building a TypeScript agent or backend? Use the SDK. You get types, autocompletion, and the operation/idempotency lifecycle for free.
Automating from a shell, cron, or CI? Use the CLI. No code, every endpoint as a command.
Connecting an AI assistant like Claude? Use MCP. Endpoints are exposed as tools the model can call after OAuth consent.
On another language or runtime? Call the API directly over HTTPS. Start at the Quickstart and API Reference.

The same action, four ways#

Each surface expresses the same operation. This is a one-off payment.

curl

request

curl -sS https://api.hightop.com/v1/agent/one-off-payments \
  -H "x-agent-id: $HIGHTOP_AGENT_ID" \
  -H "x-api-key: $HIGHTOP_API_KEY" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: payout-$(uuidgen)" \
  -d '{"to":"0x...","asset":"USDC","amount_usd":"25"}'

typescript

example

import { HightopAgentClient, createIdempotencyKey } from '@hightop/sdk'
 
const client = new HightopAgentClient({
  agentId: process.env.HIGHTOP_AGENT_ID,
  apiKey: process.env.HIGHTOP_API_KEY,
})
 
await client.request(
  'POST /v1/agent/one-off-payments',
  { to: '0x...', asset: 'USDC', amount_usd: '25' },
  { idempotencyKey: createIdempotencyKey('payout') },
)

terminal

command

hightop one-off-payments create --to 0x... --asset USDC --amount-usd 25 --pretty

json

example

{
  "name": "agent_oneOffPayments_create",
  "arguments": {
    "to": "0x...",
    "asset": "USDC",
    "amount_usd": "25",
    "idempotency_key": "payout-7f3a..."
  }
}

What every surface shares#

One catalog. The SDK methods, CLI commands, and MCP tools are all generated from the same Agent API contract, so they stay in lockstep with the Endpoints.
Amounts are strings, never floats. Bare amount fields are asset-unit amounts ("1" = 1 USDC); fields named amount_usd (used above) are USD-denominated. See Conventions.
Writes are idempotent. Every mutation takes an idempotency key; the SDK, CLI, and MCP manage or require it for you.
Operation-backed writes return operations. Money-movement mutations return an operation you poll to a terminal status; some POSTs (quotes, simulate) and webhook-management writes return their object directly. See Operations and Lifecycle and the generated endpoint metadata for exact behavior.
Errors are stable. All surfaces surface the same normalized error codes. See Errors.

Choose your surface#

The same action, four ways#

What every surface shares#

Next#