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.

Trusted-destination mutation routes are not callable or exposed in public Agent API v1. If generated artifacts list mutation routes such as adding, confirming, cancelling, or removing trusted destinations, treat them as stale or reserved and do not call them.

Catalog#

Agent Context#

Account and Balances#

Operations#

Recipients and Payments#

Transfers and Methods#

Earn, Borrow, and Conversion#

Webhooks#

Endpoint Cards#

GET /v1/agent/self#

Purpose: return the authenticated agent, scoped wallet context, permissions, limits, and current usage.

Auth and scope: header-key auth or OAuth agent:read.

Idempotency: not required.

Request: no body.

Response:

{
  "ok": true,
  "agent": {
    "id": "uuid",
    "name": "Ops Agent",
    "enabled": true,
    "wallet_address": "0x...",
    "manager_address": "0x...",
    "agent_wrapper_address": "0x...",
    "active_window": {
      "starts_at": "2026-05-16T00:00:00.000Z",
      "expires_at": null
    }
  },
  "permissions": {},
  "limits": {},
  "cannot": [
    {
      "action": "string",
      "reason": "string"
    }
  ],
  "current_usage": {}
}

permissions, limits, and current_usage are agent-specific JSON objects and may grow over time. Treat additive fields as expected. cannot enumerates actions this agent configuration blocks, which is useful for surfacing capability boundaries in your own UI.

Common errors: authentication_failed, agent_disabled, agent_not_yet_active, agent_expired, insufficient_scope.

Related recipe: Quickstart.

GET /v1/agent/balances#

Purpose: list balances for the authenticated agent wallet.

Auth and scope: header-key auth or OAuth agent:read.

Idempotency: not required.

Query:

{
  "cursor": "string, optional",
  "limit": 50
}

Response:

{
  "ok": true,
  "items": [
    {
      "asset_symbol": "USDC",
      "asset_display_name": "USD Coin",
      "amount": "1",
      "amount_usd": "1",
      "category": "cash"
    }
  ],
  "next_cursor": null,
  "has_more": false
}

amount is a decimal asset-unit string. For USDC, "1" means 1 USDC.

Common errors: authentication_failed, insufficient_scope, rate_limited.

Related recipe: Quickstart.

POST /v1/agent/recipients/resolve#

Purpose: resolve an opaque recipient identifier, address, or handle into a recipient-shaped resource.

Auth and scope: header-key auth or OAuth agent:read.

Idempotency: not required.

Request:

{
  "to": "recipient id, address, or handle",
  "asset": "USDC",
  "action": "send_payment"
}

Fields:

Response:

{
  "ok": true,
  "recipient": {
    "id": "string",
    "type": "recurring_payment",
    "display_name": "Vendor",
    "nickname": "Compute vendor",
    "asset_symbols": ["USDC"],
    "status": "active",
    "agent_actions": ["send_payment"],
    "blocked_actions": {}
  }
}

Common errors: validation_failed, not_found, recipient_not_allowed, insufficient_scope.

Related recipe: Pay a Vendor.

POST /v1/agent/payments#

Purpose: create a payment operation to an active recurring-payment recipient, active one-off payment, or currently trusted destination.

Auth and scope: header-key auth or OAuth agent:payments:write.

Idempotency: required.

Request:

{
  "to": "recipient id, address, or handle",
  "asset": "USDC",
  "amount": "1",
  "deliver_as": "auto",
  "prefer": "auto",
  "note": null,
  "slippage_percent": 1
}

Use exactly one of amount or amount_usd. amount is a decimal asset-unit string. For USDC, "1" means 1 USDC.

Fields:

Current v1 execution rejects unsupported modifiers it cannot honor. Omit note unless you have confirmed support for the specific payment path.

Response:

{
  "ok": true,
  "operation_id": "uuid",
  "status": "submitted",
  "resource": {
    "type": "payment",
    "id": "uuid"
  },
  "fee_usd": "0",
  "human_message": "string"
}

Common errors: recipient_not_allowed, permission_not_granted, asset_not_allowed, limit_exceeded, insufficient_funds, validation_failed, idempotency_key_reuse_mismatch, idempotency_request_in_progress.

Related recipe: Pay a Vendor.

POST /v1/agent/conversions/quote#

Purpose: create a 60-second, single-use conversion quote.

Auth and scope: header-key auth or OAuth agent:simulate.

Quote creation uses agent:simulate because it prices and stores a short-lived quote without broadcasting. Only POST /v1/agent/conversions requires agent:conversions:write.

Idempotency: required.

Request:

{
  "from_asset": "USDC",
  "to_asset": "ETH",
  "amount": "1",
  "slippage_percent": 1
}

Use exactly one of amount or amount_usd. amount is a decimal asset-unit string in the from_asset. slippage_percent is a number.

Response:

{
  "ok": true,
  "quote": {
    "quote_id": "uuid",
    "from_asset": "USDC",
    "to_asset": "ETH",
    "from_amount": "1",
    "expected_out": "0.0003",
    "min_amount_out": "0.000297",
    "slippage_percent": 1,
    "human_rate": "string",
    "route": {
      "legs": [
        {
          "protocol_id": "string",
          "protocol_name": "string",
          "pool_address": "0x...",
          "from_asset": "USDC",
          "to_asset": "ETH",
          "expected_out": "0.0003",
          "fee_bps": 0
        }
      ],
      "intermediate_assets": []
    },
    "expires_at": "2026-05-16T00:00:00.000Z",
    "expires_in_seconds": 60
  }
}

Common errors: validation_failed, asset_not_allowed, protocol_not_allowed, limit_exceeded, price_stale, rate_limited.

Related recipe: Convert with a Quote.

POST /v1/agent/conversions#

Purpose: execute a conversion using a previously created quote.

Auth and scope: header-key auth or OAuth agent:conversions:write.

Idempotency: required.

Request:

{
  "quote_id": "uuid"
}

Response:

{
  "ok": true,
  "operation_id": "uuid",
  "status": "submitted",
  "resource": {
    "type": "conversion",
    "id": "uuid"
  },
  "fee_usd": "0"
}

Common errors: quote_expired, quote_already_consumed, slippage_exceeded, price_stale, insufficient_funds, permission_not_granted.

Related recipe: Convert with a Quote.

GET /v1/agent/operations/{id}#

Purpose: fetch one operation scoped to the authenticated agent.

Auth and scope: header-key auth or OAuth agent:read.

Idempotency: not required.

Path params:

{
  "id": "operation uuid"
}

Query:

{
  "include": "onchain"
}

include=onchain is optional.

Response:

{
  "ok": true,
  "operation": {
    "id": "uuid",
    "idempotency_key_hash": "sha256 hex or null",
    "type": "payment",
    "status": "submitted",
    "resource": {
      "type": "payment",
      "id": "uuid"
    },
    "amount_usd": "1",
    "asset_symbol": "USDC",
    "human_message": "string",
    "fee_usd": "0",
    "created_at": "2026-05-16T00:00:00.000Z",
    "submitted_at": "2026-05-16T00:00:01.000Z",
    "executed_at": "2026-05-16T00:00:30.000Z",
    "failed_at": "2026-05-16T00:00:30.000Z",
    "error": {
      "code": "string",
      "message": "string"
    },
    "onchain": {
      "chain_id": 8453,
      "wallet_address": "0x...",
      "manager_address": "0x...",
      "agent_wrapper_address": "0x...",
      "agent_sender_address": "0x...",
      "tx_hash": "0x...",
      "user_operation_hash": "0x...",
      "bundler_hash": "0x...",
      "raw_destination_address": "0x...",
      "tx_calldata": "0x..."
    }
  }
}

Common errors: not_found, insufficient_scope, rate_limited.

Related recipe: any operation-backed recipe on this page.

POST /v1/agent/simulate#

Purpose: validate a target write request and body shape without broadcasting.

Auth and scope: header-key auth or OAuth agent:simulate.

Idempotency: not required.

Request:

{
  "method": "POST",
  "path": "/v1/agent/conversions/quote",
  "body": {
    "from_asset": "USDC",
    "to_asset": "ETH",
    "amount": "1",
    "slippage_percent": 1
  }
}

method may be POST, PATCH, or DELETE. path must start with /v1/agent/.

The simulate wrapper accepts body as an object and then validates it against the target route. Simulation validates request shape only. It does not check balances, permissions, LTV, recipient policy, quote freshness, fees, or broadcast viability.

Response:

{
  "ok": true,
  "would_succeed": true,
  "execution_path": ["validation"],
  "blocks": []
}

Common errors: validation_failed, insufficient_scope.

Related recipe: Quickstart.

POST /v1/agent/earn/deposit#

Purpose: create an earn deposit operation.

Auth and scope: header-key auth or OAuth agent:earn:write.

Idempotency: required.

Request:

{
  "asset": "USDC",
  "amount": "1",
  "use_best_available": true
}

Use exactly one of amount or amount_usd. Use exactly one of vault_id or use_best_available: true. amount is a decimal asset-unit string.

Response:

{
  "ok": true,
  "operation_id": "uuid",
  "status": "submitted",
  "resource": {
    "type": "earn_position",
    "id": "uuid"
  },
  "fee_usd": "0"
}

Common errors: validation_failed, asset_not_allowed, protocol_not_allowed, insufficient_funds, permission_not_granted, limit_exceeded.

Related recipe: Move Funds into Earn.

POST /v1/agent/withdrawals/to-bank#

Purpose: create a bank withdrawal operation to an owner-linked bank method that passes the authenticated wallet's trust checks.

Auth and scope: header-key auth or OAuth agent:withdrawals:write.

Idempotency: required.

Request:

{
  "method_id": "bank-method-id",
  "asset": "USDC",
  "amount": "1",
  "note": null
}

Use exactly one of amount or amount_usd. amount is a decimal asset-unit string. For USDC, "1" means 1 USDC. Current v1 execution rejects unsupported non-empty withdrawal notes, so omit note unless support is confirmed.

Response:

{
  "ok": true,
  "operation_id": "uuid",
  "status": "submitted",
  "resource": {
    "type": "withdrawal",
    "id": "uuid"
  },
  "fee_usd": "0"
}

Common errors: validation_failed, recipient_not_allowed, permission_not_granted, insufficient_funds, limit_exceeded.

Related recipe: Withdraw to a Bank.

POST /v1/agent/webhooks#

Purpose: create an outbound webhook endpoint.

Auth and scope: header-key auth or OAuth agent:webhooks:manage.

Idempotency: required.

Request:

{
  "url": "https://example.com/hightop/webhook",
  "description": "Production webhook",
  "event_types": ["payment.executed", "conversion.executed"]
}

event_types accepts only currently subscribable event types, not every reserved event in the full vocabulary.

Response:

{
  "ok": true,
  "webhook": {
    "id": "uuid",
    "url": "https://example.com/hightop/webhook",
    "description": "Production webhook",
    "event_types": ["payment.executed", "conversion.executed"],
    "enabled": true,
    "disabled_reason": null,
    "consecutive_failures": 0,
    "last_delivered_at": null,
    "last_failure_at": null,
    "created_at": "2026-05-16T00:00:00.000Z",
    "updated_at": "2026-05-16T00:00:00.000Z"
  },
  "signing_secret": "shown once"
}

Common errors: validation_failed, limit_exceeded, idempotency_key_reuse_mismatch, insufficient_scope.

Related recipe: Verify a Webhook.

PATCH /v1/agent/webhooks/{id}#

Purpose: update an outbound webhook endpoint.

Auth and scope: header-key auth or OAuth agent:webhooks:manage.

Idempotency: required.

Path params:

{
  "id": "webhook endpoint uuid"
}

Request:

{
  "url": "https://example.com/hightop/webhook",
  "description": "Updated webhook",
  "event_types": ["payment.executed"],
  "enabled": true
}

At least one field is required. event_types accepts only currently subscribable event types. If an endpoint was auto-disabled for sustained failures, enabled: true is owner-only and returns owner_only_action.

Response:

{
  "ok": true,
  "webhook": {
    "id": "uuid",
    "url": "https://example.com/hightop/webhook",
    "description": "Updated webhook",
    "event_types": ["payment.executed"],
    "enabled": true,
    "disabled_reason": null,
    "consecutive_failures": 0,
    "last_delivered_at": null,
    "last_failure_at": null,
    "created_at": "2026-05-16T00:00:00.000Z",
    "updated_at": "2026-05-16T00:05:00.000Z"
  }
}

Common errors: validation_failed, not_found, owner_only_action, idempotency_key_reuse_mismatch, insufficient_scope.

Related recipe: Verify a Webhook.

DELETE /v1/agent/webhooks/{id}#

Purpose: delete an outbound webhook endpoint.

Auth and scope: header-key auth or OAuth agent:webhooks:manage.

Idempotency: required.

Path params:

{
  "id": "webhook endpoint uuid"
}

Request: no body.

Response:

{
  "ok": true,
  "webhook": {
    "id": "uuid",
    "url": "https://example.com/hightop/webhook",
    "description": "Production webhook",
    "event_types": ["payment.executed"],
    "enabled": true,
    "disabled_reason": null,
    "consecutive_failures": 0,
    "last_delivered_at": null,
    "last_failure_at": null,
    "created_at": "2026-05-16T00:00:00.000Z",
    "updated_at": "2026-05-16T00:05:00.000Z"
  }
}

Common errors: not_found, idempotency_key_reuse_mismatch, insufficient_scope.

Related recipe: Verify a Webhook.

GET /v1/agent/webhooks/{id}/deliveries#

Purpose: list delivery attempts for one outbound webhook endpoint.

Auth and scope: header-key auth or OAuth agent:read.

Idempotency: not required.

Path params:

{
  "id": "webhook endpoint uuid"
}

Query:

{
  "status": "delivered",
  "event_id": "uuid",
  "cursor": "uuid",
  "limit": 50
}

status, event_id, cursor, and limit are optional. cursor is a delivery UUID and is valid only for the same endpoint and active filters.

Response:

{
  "ok": true,
  "items": [
    {
      "id": "uuid",
      "event_id": "uuid",
      "event_type": "payment.executed",
      "event_created_at": "2026-05-16T00:00:00.000Z",
      "endpoint_id": "uuid",
      "attempt": 1,
      "status": "delivered",
      "http_status": 200,
      "error_class": null,
      "latency_ms": 120,
      "response_body": "ok",
      "next_attempt_at": null,
      "first_attempt_at": "2026-05-16T00:00:00.000Z",
      "last_attempt_at": "2026-05-16T00:00:00.000Z",
      "terminal_at": "2026-05-16T00:00:00.000Z",
      "created_at": "2026-05-16T00:00:00.000Z",
      "updated_at": "2026-05-16T00:00:00.000Z"
    }
  ],
  "next_cursor": null,
  "has_more": false
}

Common errors: not_found, validation_failed, insufficient_scope, rate_limited.

Related recipe: Verify a Webhook.