Pay a Vendor#

Use this when an agent needs to pay an existing recurring-payment recipient, active one-off payment, or trusted destination.

Prerequisites#

• The Hightop agent is active.
• The recipient or destination is already configured in the app.
• The agent has payment permission and enough limit headroom.

Resolve the Recipient#

curl -sS https://api.hightop.com/v1/agent/recipients/resolve \
  -H "content-type: application/json" \
  -H "x-agent-id: $HIGHTOP_AGENT_ID" \
  -H "x-api-key: $HIGHTOP_API_KEY" \
  -d '{
    "to": "vendor@example.com",
    "asset": "USDC",
    "action": "send_payment"
  }'

recipients/resolve does not require Idempotency-Key.

Use the returned recipient.id in the payment request when possible. The payment endpoint can also accept a handle or address directly, but resolving first lets you inspect status and blocked actions before asking Hightop to move funds.

Create the Payment#

Agent API amount fields are decimal asset-unit strings. For USDC, "1" means 1 USDC.

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: vendor-payment-$(uuidgen)" \
  -d '{
    "to": "resolved-recipient-id",
    "asset": "USDC",
    "amount": "1",
    "prefer": "auto"
  }'

Optional TypeScript SDK Shape#

const payment = await client.v1.agent.postPayments(
  {
    to: 'resolved-recipient-id',
    asset: 'USDC',
    amount: '1',
    prefer: 'auto',
  },
  { idempotencyKey: `vendor-payment-${crypto.randomUUID()}` },
)

Follow Up#

Poll:

curl -sS "https://api.hightop.com/v1/agent/operations/$OPERATION_ID" \
  -H "x-agent-id: $HIGHTOP_AGENT_ID" \
  -H "x-api-key: $HIGHTOP_API_KEY"

Or subscribe to payment.executed, payment.execution_failed, and operation.policy_rejected webhooks.

Likely errors: recipient_not_allowed, permission_not_granted, asset_not_allowed, limit_exceeded, insufficient_funds, idempotency_key_reuse_mismatch.