--- seo: description: >- agentsub account and merchant-access API. AgentID identifies agents; Clerk authenticates human owners. Registered merchants own their application delivery and… sidebar: label: Overview title: agentsub Gateway API --- agentsub account and merchant-access API. AgentID identifies agents; Clerk authenticates human owners. Registered merchants own their application delivery and payment terms. Agents of one verified owner share eligible credit lots while retaining separate clearance, caps and spending history. 1 credit = $0.01 = 1,000,000 integer microcredits. JSON money amounts use exact decimal strings. Free application access checks create no hold, debit or payment. Paid checks return a requirement, never an entitlement or receipt. Link payment directly to merchants is the primary paid-service integration; credits are optional when accepted by the merchant. Direct seller settlement is not currently enabled. Optional account-credit Checkout requires its own configuration and authoritative successful Stripe receipt. Human configuration/payment controls reject agents. Merchant keys are hashed, scoped and revocable. OAuth uses PKCE S256 and exact resource audiences. Mutations document their idempotency requirements. Secret issuance replays omit plaintext. Historical grants and journal entries remain intact; retired provider connectors and key imports are unavailable. Merchant vouchers are agent-, offer-, audience- and amount-bound. Capture records canonical ledger payables, not completed fiat payouts. Signed webhooks are delivered at least once and receivers deduplicate event IDs. Trading, cash-out, x402, inference offers and subscription billing are not available. Version 0.4.0 Base URL: `https://api.agentsub.dev` ## Health - [`GET /health`](/reference/health/get-health) — Liveness and mode report. ## Discovery - [`GET /v1/openapi.json`](/reference/discovery/get-open-api-document) — Served OpenAPI document. - [`GET /.well-known/jwks.json`](/reference/discovery/get-jwks) — Voucher signing JWKS (ES256). - [`GET /.well-known/acs-configuration`](/reference/discovery/get-acs-configuration) — ACS payment configuration. - [`GET /v1/integrations`](/reference/discovery/get-integrations) — Integration status report. ## OAuth - [`GET /.well-known/oauth-authorization-server`](/reference/o-auth/get-o-auth-authorization-server-metadata) — OAuth authorization server metadata. - [`GET /.well-known/oauth-protected-resource`](/reference/o-auth/get-o-auth-protected-resource-metadata) — Protected resource metadata (API). - [`GET /.well-known/oauth-protected-resource/mcp`](/reference/o-auth/get-o-auth-protected-resource-metadata-mcp) — Protected resource metadata (MCP). - [`GET /oauth/jwks`](/reference/o-auth/get-o-auth-jwks) — OAuth access-token signing JWKS. - [`POST /oauth/register`](/reference/o-auth/oauth-register-client) — Dynamic client registration (RFC 7591). - [`GET /oauth/authorize`](/reference/o-auth/oauth-authorize) — Authorization endpoint (302 to AgentID). - [`GET /oauth/callback`](/reference/o-auth/oauth-callback) — AgentID authorization callback. - [`POST /oauth/token`](/reference/o-auth/oauth-token) — Token endpoint (authorization\_code + PKCE). - [`GET /oauth/request`](/reference/o-auth/get-o-auth-authorization-request) — Read sanitized pending OAuth consent context. - [`POST /oauth/select`](/reference/o-auth/select-o-auth-agent-identity) — Choose AgentID login. - [`POST /oauth/owner/consent`](/reference/o-auth/consent-o-auth-human-owner) — Explicit human owner OAuth consent. - [`POST /oauth/social/connect`](/reference/o-auth/connect-verified-clerk-agent-id-account) — Renew an AgentID social identity through the registered direct broker. ## Owner - [`GET /v1/owner/overview`](/reference/owner/get-owner-overview) — Owner dashboard overview. - [`PATCH /v1/owner/agents/{id}/caps`](/reference/owner/update-agent-caps) — Update agent spending policy. - [`POST /v1/owner/agents/{id}/freeze`](/reference/owner/freeze-agent) — Freeze or unfreeze an agent. - [`POST /v1/owner/agents/{id}/avatar/upload`](/reference/owner/start-avatar-upload) — Start agent avatar upload. - [`POST /v1/owner/agents/{id}/avatar/finalize`](/reference/owner/finalize-avatar-upload) — Finalize agent avatar upload. - [`PATCH /v1/owner/agents/{id}/profile`](/reference/owner/update-agent-profile) — Update agent display profile. ## Agent - [`GET /v1/me`](/reference/agent/get-me) — Authenticated agent identity. - [`GET /v1/balance`](/reference/agent/get-balance) — Agent credit balance. - [`GET /v1/history`](/reference/agent/get-history) — Agent ledger history. - [`POST /v1/agents/register`](/reference/agent/register-agent) — Register the authenticated agent. - [`GET /v1/catalog`](/reference/agent/get-catalog) — Offer catalog. - [`GET /v1/offers/{id}`](/reference/agent/get-offer) — Offer detail. - [`POST /v1/quotes`](/reference/agent/create-quote) — Quote an offer. - [`POST /v1/vouchers`](/reference/agent/create-voucher) — Mint an ACS voucher (hold). ## Services - [`POST /v1/access/check`](/reference/services/check-access) — Check application access for the authenticated agent. ## Payments - [`GET /v1/payments/status`](/reference/payments/get-payments-status) — Payment provider connection status. - [`POST /v1/payments/checkout`](/reference/payments/create-checkout) — Create a Link checkout session. - [`POST /v1/payments/link/connect`](/reference/payments/connect-link) — Start Link connect (owner only). - [`GET /v1/payments/link/callback`](/reference/payments/link-callback-get) — Link OAuth callback (GET). - [`POST /v1/payments/link/callback`](/reference/payments/link-callback-post) — Link OAuth callback (POST). - [`POST /v1/payments/topups`](/reference/payments/request-topup) — Request an agent top-up approval. - [`GET /v1/payments/topups/{id}`](/reference/payments/poll-topup) — Poll a top-up request. - [`POST /v1/payments/stripe/webhook`](/reference/payments/stripe-webhook) — Stripe webhook receiver (inbound only). ## Merchant Registry - [`GET /v1/merchants`](/reference/merchant-registry/list-merchants) — List registered merchants. - [`POST /v1/merchants`](/reference/merchant-registry/create-merchant) — Register a merchant. - [`GET /v1/merchants/{id}`](/reference/merchant-registry/get-merchant) — Merchant detail. - [`POST /v1/merchants/{id}/verify-domain`](/reference/merchant-registry/verify-merchant-domain) — Verify merchant domain via DNS TXT. - [`POST /v1/merchants/{id}/offers`](/reference/merchant-registry/publish-merchant-offer) — Publish a merchant offer. - [`PATCH /v1/merchants/{id}/offers/{offerId}`](/reference/merchant-registry/update-merchant-offer) — Update a merchant offer. - [`DELETE /v1/merchants/{id}/offers/{offerId}`](/reference/merchant-registry/delete-merchant-offer) — Delete a merchant offer. - [`GET /v1/merchants/{id}/api-keys`](/reference/merchant-registry/list-merchant-api-keys) — List merchant API keys (metadata only). - [`POST /v1/merchants/{id}/api-keys`](/reference/merchant-registry/create-merchant-api-key) — Issue a scoped merchant API key. - [`DELETE /v1/merchants/{id}/api-keys/{keyId}`](/reference/merchant-registry/revoke-merchant-api-key) — Revoke a merchant API key. - [`GET /v1/merchants/catalog`](/reference/merchant-registry/get-registered-merchant-catalog) — Active verified merchant offers. ## Merchant Scoped - [`GET /v1/redemptions/{id}`](/reference/merchant-scoped/get-redemption) — Fetch a redemption (hold) record. - [`POST /v1/redemptions/{id}/capture`](/reference/merchant-scoped/capture-redemption) — Capture a hold. - [`POST /v1/redemptions/{id}/release`](/reference/merchant-scoped/release-redemption) — Release a hold. - [`POST /v1/vouchers/introspect`](/reference/merchant-scoped/introspect-voucher) — Verify an ACS voucher offline-equivalent. ## MCP - [`POST /mcp`](/reference/mcp/mcp-post) — Model Context Protocol HTTP endpoint. - [`GET /mcp`](/reference/mcp/mcp-get) — Unsupported stateless MCP method. - [`DELETE /mcp`](/reference/mcp/mcp-delete) — Unsupported stateless MCP method. ## Merchant Webhooks - [`GET /v1/merchants/{id}/webhook`](/reference/merchant-webhooks/get-merchant-webhook) — Read webhook configuration. - [`PUT /v1/merchants/{id}/webhook`](/reference/merchant-webhooks/configure-merchant-webhook) — Configure verified-domain webhook; secret shown once. - [`DELETE /v1/merchants/{id}/webhook`](/reference/merchant-webhooks/disable-merchant-webhook) — Disable webhook delivery. - [`POST /v1/merchants/{id}/webhook/rotate`](/reference/merchant-webhooks/rotate-merchant-webhook) — Rotate webhook HMAC secret; secret shown once. - [`GET /v1/merchants/{id}/webhook/events`](/reference/merchant-webhooks/list-merchant-webhook-events) — Read webhook delivery events and actual attempt receipts.