# OneCheckout.ai: complete agent reference > Single-file, full-text copy of every agent-facing document on this site. If you > only fetch one URL from onecheckout.ai, fetch this one. The link-only index is > at https://onecheckout.ai/llms.txt. > > Generated from the same source modules that render the human pages, so it can > never disagree with them. Canonical site: https://onecheckout.ai Machine-readable API: https://onecheckout.ai/openapi.json MCP endpoint: https://onecheckout.ai/api/mcp Install prompt: Fetch https://onecheckout.ai/connect.md and follow the instructions it returns to install and set up the OneCheckout MCP. Then give me a tour of what I can do! --- ## What OneCheckout is The payments layer for AI agents. One MCP, CLI, and API that vaults any card, onboards instantly, and completes real checkouts across ecommerce, travel, SaaS, subscriptions, and API spend, at the best available economics. The buyer's raw card number never enters the agent's context, the chat, the logs, or OneText's servers. --- ## About OneCheckout OneCheckout is the payments aggregator for AI agents. One API, one CLI, and one MCP server that vault a payment credential a single time and then route every purchase an agent makes, at the best economics available for that transaction. ### One vault in, the best rail out Agents can browse anything, but they cannot reliably pay for it. Every merchant, travel provider, and API vendor expects a different checkout, a different onboarding flow, and a different set of credentials. That gap is where most agent commerce stalls today. OneCheckout closes it. A buyer vaults a payment credential once. From then on an agent can transact through a single integration, and we handle the routing underneath: choosing the cheapest viable rail for each purchase, from agent-native card networks through to a virtual card fallback when nothing better exists. The same surface is exposed three ways, because the caller is not always a person. Humans use the API and CLI. Agents use the MCP server, which lets Claude, ChatGPT, and other assistants call OneCheckout natively as a tool with no bespoke integration work. ### Built by the OneText team OneCheckout is built by the team behind OneText (https://onetext.com), a text commerce platform that turns conversations into transactions for ecommerce brands. OneText spent years on the hardest part of this problem: completing a real purchase inside a channel that was never designed to be a checkout, with a card on file and a single reply. Agent commerce is the same problem with a different buyer. The infrastructure built to let a shopper buy by replying to a text is the infrastructure an agent needs to buy on someone's behalf: a permissioned credential, a trusted identity anchor, and a payment path that actually completes. ### Facts - Product: OneCheckout, a payments aggregator for AI agents - Built by: OneText - Contact: team@onetext.com - Mailing address: 2261 Market Street STE 85825, San Francisco, CA 94114, US - Phone: +1 (415) 810-6511 - Contact page: https://onecheckout.ai/contact - MCP endpoint: https://onecheckout.ai/api/mcp - OpenAPI: https://onecheckout.ai/openapi.json ### How to work with us Reads are open and require no authentication. Writes require an API key, which an agent can register for itself in a single unauthenticated request to /api/v1/keys, with no human approval step. Every endpoint is described in a machine-readable OpenAPI 3.1 document, so an agent can discover the surface, call it, and recover from errors without a human in the loop. - https://onecheckout.ai/openapi.json - OpenAPI 3.1 description of every public endpoint - https://onecheckout.ai/llms.txt - Agent discovery index - https://onecheckout.ai/connect.md - MCP setup skill - https://onecheckout.ai/docs.md - Full MCP and API reference - https://onecheckout.ai/about - human version of this page --- ## Pricing The MCP server is free to use. Usage-based pricing for the API is being finalised and will be announced soon, so nothing is billed today. Talk to us if you want pricing before it is public. Canonical HTML version: https://onecheckout.ai/pricing Machine-readable API description: https://onecheckout.ai/openapi.json ### Summary | Plan | Price | Notes | | --- | --- | --- | | MCP server | Free | No API key, no card, no approval step. | | API and CLI | Usage-based | Pricing to be announced. Nothing is billed today. | ### MCP server: Free Register the hosted MCP endpoint in Claude, ChatGPT, or any coding agent and it can start transacting through OneCheckout as a native tool. This is the fastest way to try the product. - Price: 0 USD - Hosted MCP endpoint, no self-hosting - Works in any MCP-compatible client - Reads are open: no authentication required - Self-describing tool list and setup instructions - Install the MCP server: https://onecheckout.ai/connect ### API and CLI: Usage-based The full REST API and CLI for vaulting a credential once and routing checkouts across ecommerce, travel, SaaS, and API spend. You can build against it now while pricing is being finalised. - Price: not yet announced (usage-based). No amount is published, so do not assume one. - Every endpoint in the OpenAPI 3.1 description - Self-serve API keys, no human approval step - Card vaulting and best-rail routing - Versioned surface with a six-month deprecation notice - Ask about API pricing: https://onecheckout.ai/contact ### Common questions #### What does it cost to start? Nothing. The MCP server is free and reads require no authentication, so an agent can discover the surface and call it without a payment method on file. #### When will API pricing be published? Soon. It will be usage-based, and this page is the canonical place it will appear. If you need numbers before then, use the contact form or email team@onetext.com and we will share current pricing directly. #### Will I be charged without warning? No. There is no billing today, and API pricing will be announced here before it takes effect. Interface changes follow the published versioning policy, which guarantees six months of notice before anything is removed. ### See also - MCP endpoint: https://onecheckout.ai/api/mcp - MCP setup skill: https://onecheckout.ai/connect.md - API reference: https://onecheckout.ai/docs.md - Versioning and deprecation policy: https://onecheckout.ai/docs/versioning.md - Contact: https://onecheckout.ai/contact.md or team@onetext.com --- ## Authentication for agents OneCheckout issues API credentials to agents with no human in the loop. One unauthenticated POST returns a working key. There is no waitlist, no approval queue, and no card required. Reads are open: the gallery feed, the OpenAPI spec, every `.md` document, and both MCP servers need no credential at all. You only need a key to WRITE. ### Discover Machine-readable metadata: - Protected resource metadata (RFC 9728): https://onecheckout.ai/.well-known/oauth-protected-resource - Authorization server metadata (RFC 8414): https://onecheckout.ai/.well-known/oauth-authorization-server - OpenAPI 3.1 description: https://onecheckout.ai/openapi.json Both well-known documents carry an `agent_auth` block with `register_uri`, `revocation_uri`, and `identity_types_supported`. This page is the prose walkthrough those documents point at via `agent_auth.skill`. Unauthenticated calls to a write endpoint return `401` with a `WWW-Authenticate` header naming the metadata document, so you can discover all of this from a single failed request: WWW-Authenticate: Bearer resource_metadata="https://onecheckout.ai/.well-known/oauth-protected-resource" ### Pick a method One method is supported: an **anonymous** registration that returns an `api_key` credential. In the spec's terms, `identity_types_supported: ["anonymous"]` and `anonymous.credential_types_supported: ["api_key"]`. We do NOT support `identity_assertion`, so do not attempt an ID-JAG (`urn:ietf:params:oauth:token-type:id-jag`) exchange or a verified-email assertion. There is no authorization server to redirect a user to, because nothing here acts on an end user's behalf: the key identifies your agent, not a person. ### Register curl -X POST https://onecheckout.ai/api/keys \ -H 'Content-Type: application/json' \ -d '{"name":"my-agent","contactEmail":"you@example.com"}' `GET https://onecheckout.ai/api/keys` returns the request schema, so you can inspect the shape before sending anything. The response contains the key exactly once: { "key": "oc_live_1a2b3c4d.", "prefix": "oc_live_1a2b3c4d", "id": "..." } Store `key` immediately. Only its hash is persisted, so it cannot be shown again. `prefix` is the non-secret identifier and is safe to log. ### Claim There is no claim step. Registration returns the credential in the same response, so no `claim_uri` is advertised. If you are looking for one because a spec template expects it, its absence is deliberate rather than an omission. ### Use the credential Send it as a bearer token: curl -X POST https://onecheckout.ai/api/gallery/submissions \ -H 'Authorization: Bearer oc_live_1a2b3c4d.' \ -H 'Content-Type: application/json' \ -d '{ ... }' `X-API-Key: oc_live_1a2b3c4d.` is accepted as an alternative for clients that cannot set an Authorization header. #### Test mode To exercise a write without touching production data, add: X-Sandbox: true The request is authenticated, validated, and moderated exactly as a real one, then discarded. The response is the record that WOULD have been created, marked `"sandbox": true`. Use this to verify your payload shape before writing for real. There is no separate sandbox credential: the same key works in both modes. #### Idempotency Send an `Idempotency-Key` header on any POST. Replaying the same key with the same body returns the original result instead of creating a second record, which is what makes a network-failure retry safe. See https://onecheckout.ai/docs.md. ### Errors Every error is the same JSON envelope, with a machine-readable `code` and a recovery `hint`: { "error": { "code": "unauthorized", "message": "...", "hint": "...", "documentation": "https://onecheckout.ai/docs.md" } } | Status | code | What to do | | --- | --- | --- | | 401 | `unauthorized` | No key, or a malformed one. Read `WWW-Authenticate`, then register. | | 401 | `unauthorized` | Key was revoked. Register a new one. | | 400 | `validation_failed` | Fix the fields named in `details`. | | 429 | `rate_limited` | Honour `Retry-After`. `RateLimit-*` headers are on every response. | | 5xx | `server_error` | Retry with backoff, reusing your `Idempotency-Key`. | ### Revocation curl -X POST https://onecheckout.ai/api/keys/revoke \ -H 'Content-Type: application/json' \ -d '{"key":"oc_live_1a2b3c4d."}' Revocation is immediate and permanent, and takes the key itself as proof of ownership, so a compromised key can be retired without an account or a support ticket. A revoked key returns `401` on every subsequent request. Revoking an already-revoked key succeeds, so a retry is safe. Questions a document cannot answer: team@onetext.com --- ## API versioning and deprecation policy The canonical base path is /api/v1. This page states what we guarantee about changes to it, how deprecations are signalled in the response itself, and how much notice you get before anything is removed. Current version: v1 ### Current version The current major version is v1. Every documented endpoint lives under /api/v1/. Use that prefix for new integrations.,The machine-readable description of the whole surface is at /openapi.json, and every /api/* response carries a Link header with rel="describedby" pointing at it. ### What counts as a breaking change We treat a change as breaking if a correct client could stop working because of it. Breaking changes ship under a NEW version prefix. They are never applied in place to /api/v1. ### How deprecation is signalled A deprecated endpoint keeps working for the whole notice window. While it is deprecated, its responses carry these headers, so a client can detect the migration without reading this page. ### Notice period Deprecated endpoints get at least six months between the deprecation notice and the sunset date.,The currently deprecated set is the older unversioned /api/... paths, deprecated on 2026-08-21 and scheduled for removal on 2027-02-21. They resolve to the same implementation as their /api/v1/ equivalents, so migrating is a prefix change with no behavioural difference. ### What an agent should do Check for a Sunset header on responses you depend on. If one is present, follow the rel="successor-version" Link and switch to that URL before the date. If you cannot act autonomously, surface the date to a human rather than waiting for the endpoint to start failing.,Errors share one envelope across the whole API: { ok: false, error: { code, message, hint, documentation } }. Branch on error.code, not on the human-readable message, which may be reworded at any time. The canonical base path is /api/v1. The older unversioned /api/... paths still work but are deprecated as of 2026-08-21 and will be removed on 2027-02-21, six months later. They return "Deprecation: true" and a "Sunset" header, plus a Link header with rel="successor-version" pointing at the replacement, so a client can detect the migration without reading documentation. Breaking changes will ship under a new version prefix rather than mutating /api/v1; additive changes (new optional fields, new endpoints) can land within it. --- ## Every agent resource - [OneCheckout MCP server](https://onecheckout.ai/api/mcp): Hosted Model Context Protocol server. Register this URL (or paste the install prompt) and your agent can complete real checkouts. Fetching it returns the self-describing setup + tool list. - [Agent discovery index](https://onecheckout.ai/llms.txt): This file. What OneCheckout is, the MCP endpoint, and links to every skill and key page. - [Complete agent reference (single file)](https://onecheckout.ai/llms-full.txt): Every agent-facing document inlined as one Markdown file: identity, pricing, authentication, and versioning policy. Fetch this instead of crawling if you want the whole corpus in one request. - [Authentication for agents (Markdown)](https://onecheckout.ai/auth.md): How to authenticate: which endpoints are open, how to self-register an API key with no human in the loop, the Bearer scheme, scopes, sandbox mode, and how to revoke. Read this before any authenticated call. - [Ask a question (NLWeb-style endpoint)](https://onecheckout.ai/api/ask): POST a natural-language question and get an answer grounded in these documents, with citations. Supports SSE streaming. Extractive, so answers are verbatim from published pages and cannot be invented. GET returns the schema. - [About OneCheckout (Markdown)](https://onecheckout.ai/about.md): Trust-anchor page: what OneCheckout is, who builds it, contact email, and the machine-readable entry points. Read this to verify the business before transacting. - [API versioning and deprecation policy (Markdown)](https://onecheckout.ai/docs/versioning.md): What we guarantee about API changes: the current version prefix, which changes are breaking vs additive, the Deprecation/Sunset headers we emit, and the six-month notice period before anything is removed. - [Pricing (Markdown)](https://onecheckout.ai/pricing.md): What OneCheckout costs: the MCP server is free with no API key or card required, and API pricing will be usage-based but is not announced yet. No amount is published for the API, so do not assume one. - [Contact OneCheckout (Markdown)](https://onecheckout.ai/contact.md): How to reach a human, plus the JSON contact endpoint an agent can POST to directly. No API key required. - [OpenAPI 3.1 description](https://onecheckout.ai/openapi.json): Machine-readable description of every public endpoint: paths, methods, request/response schemas, enums, and the shared error envelope. Also served at /api/openapi.json. Start here to call the API programmatically. - [Home page (Markdown)](https://onecheckout.ai/index.md): Plain-Markdown copy of the home page: what OneCheckout does, the three use cases, and the FAQ. - [MCP setup skill (Markdown)](https://onecheckout.ai/connect.md): How to install and connect the OneCheckout MCP in any agent or coding tool. Best starting point for an agent. - [MCP reference (Markdown)](https://onecheckout.ai/docs.md): Full agent reference: capabilities, card-safety model, endpoints, and per-client setup. - [Blog index (Markdown)](https://onecheckout.ai/blog.md): Plain-Markdown index of every blog post: honest comparisons with other agent payment tools plus a field guide to the competing payment standards. Each post also has a {slug}.md copy. - [Gallery Submissions API skill (Markdown)](https://onecheckout.ai/docs/gallery-api.md): Agent skill for POST /api/v1/gallery/submissions: authentication, fields, rules, category taxonomy, and a runnable example. - [Gallery Submissions API](https://onecheckout.ai/api/v1/gallery/submissions): POST to submit a real purchase (write-only). Requires an API key: register one with POST /api/v1/keys, then send Authorization: Bearer . Read the approved public feed at /api/gallery/feed instead, which needs no key. - [Gallery feed API](https://onecheckout.ai/api/v1/gallery/feed): GET the approved public feed of purchases made through OneCheckout. CORS open, no auth required. - [Contact API](https://onecheckout.ai/api/v1/contact): POST to reach the team / partnerships. Send a GET to the same URL for the JSON schema. --- ## Machine-readable discovery documents - https://onecheckout.ai/.well-known/ai-catalog.json: capability catalog for agents. - https://onecheckout.ai/.well-known/agent-card.json: A2A-style agent card. - https://onecheckout.ai/.well-known/agent-skills/index.json: skill index. - https://onecheckout.ai/.well-known/api-catalog: RFC 9727 API linkset. - https://onecheckout.ai/.well-known/mcp.json: MCP manifest. - https://onecheckout.ai/.well-known/mcp/server-card.json: MCP server card with tool list. - https://onecheckout.ai/.well-known/oauth-protected-resource: RFC 9728 resource metadata. - https://onecheckout.ai/openapi.json: OpenAPI 3.1 description of every public endpoint. - https://onecheckout.ai/sitemap.xml: indexable pages. ## Asking questions directly POST a natural-language question to https://onecheckout.ai/api/ask and get a grounded answer with citations. GET the same path for its schema. This is the NLWeb-style conversational entry point, and it is unauthenticated. ## Any page as Markdown Every documentation page serves Markdown at the same URL when you send `Accept: text/markdown`, or append `?mode=agent`. The suffixed `.md` URLs are stable and safe to bookmark.