> ## Documentation Index > Fetch the complete documentation index at: https://openrouter.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Buy credits with a machine payment > Starts an agent credit purchase paid with a Machine Payments Protocol (MPP) credential: USDC on Tempo, or a card when one is offered. The first call answers `402` with one `WWW-Authenticate: Payment ...` challenge per payment option; pay one of them and retry the same request, same `Idempotency-Key`, with the signed credential in `Payment-Authorization: Payment ...` (or in `Authorization: Payment ...` when the management key is sent as `X-Api-Key`). A paid request answers `202`: the transfer was broadcast or the card was charged, and the payment is still being confirmed, so credits arrive asynchronously. Poll the URL in the `Location` header, `GET /api/v1/credits/purchases/{id}`, until `status` is `credited` or `failed`. ## OpenAPI ````yaml /openapi/openapi.yaml post /credits/purchases openapi: 3.1.0 info: contact: email: support@openrouter.ai name: OpenRouter Support url: https://openrouter.ai/docs description: OpenAI-compatible API with additional OpenRouter features license: name: MIT url: https://opensource.org/licenses/MIT title: OpenRouter API version: 1.0.0 servers: - description: Production server url: https://openrouter.ai/api/v1 x-speakeasy-server-id: production security: - apiKey: [] tags: - description: API key management endpoints name: API Keys - description: Analytics and usage endpoints name: Analytics - description: Anthropic Messages endpoints name: Anthropic Messages - description: BYOK endpoints name: BYOK - description: >- Submit, list, poll, and delete asynchronous batches of inference requests. See https://openrouter.ai/docs/batch-quickstart. name: Batch - description: Benchmarks endpoints name: Benchmarks - description: Chat completion endpoints name: Chat - description: Task classification market-share endpoints name: Classifications - description: Containers endpoints name: Containers - description: Credit management endpoints name: Credits - description: >- Public OpenRouter usage datasets. Data returned by these endpoints is licensed under CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/): reuse and republish it, including commercially, with attribution to OpenRouter. name: Datasets - description: Text embedding endpoints name: Embeddings - description: Endpoint information name: Endpoints - description: External Users endpoints name: External Users - description: Files endpoints name: Files - description: Generation history endpoints name: Generations - description: Guardrail Policies endpoints name: Guardrail Policies - description: Guardrails endpoints name: Guardrails - description: Images endpoints name: Images - description: Model information endpoints name: Models - description: OAuth authentication endpoints name: OAuth - description: Observability endpoints name: Observability - description: Organization endpoints name: Organization - description: Presets endpoints name: Presets - description: Private Endpoints endpoints name: Private Endpoints - description: Private Providers endpoints name: Private Providers - description: Provider information endpoints name: Providers - description: Rerank endpoints name: Rerank - description: OpenAI-compatible Responses API endpoints name: Responses - description: >- Management endpoints for SCIM group-to-workspace mappings, authenticated with a management key. These are not the SCIM 2.0 connector endpoints for your identity provider. In your identity provider, enter the SCIM endpoint URL shown when you enable provisioning under Settings > Members > SCIM Mappings. See https://openrouter.ai/docs/guides/features/scim-mappings#set-up-provisioning. name: SCIM - description: Speech-to-text endpoints name: STT x-displayName: Transcriptions - description: >- System One endpoints for models such as Jev, compatible with the TypeSafe SDKs. See https://openrouter.ai/docs/guides/community/typesafe-sdk. name: SystemOne x-displayName: System One - description: Text-to-speech endpoints name: TTS x-displayName: Speech - description: >- The catalog of server tools OpenRouter runs on behalf of a model: accepted `tools[].type` spellings per API format, engines and pricing, and which endpoints run each tool natively. See https://openrouter.ai/docs/guides/features/server-tools. name: Tools - description: >- Store host-bound secrets for a workspace or for one intern. Scope is selected by the API key. Responses return metadata only, never secret values. See https://openrouter.ai/docs/guides/ori/vault. name: Vault - description: Video Generation endpoints name: Video Generation - description: Workspaces endpoints name: Workspaces - description: Alpha feature endpoints for Decisions requests name: alpha.decisions - description: Alpha feature endpoints for Extractions requests name: alpha.extractions externalDocs: description: OpenRouter Documentation url: https://openrouter.ai/docs paths: /credits/purchases: post: tags: - Credits summary: Buy credits with a machine payment description: >- Starts an agent credit purchase paid with a Machine Payments Protocol (MPP) credential: USDC on Tempo, or a card when one is offered. The first call answers `402` with one `WWW-Authenticate: Payment ...` challenge per payment option; pay one of them and retry the same request, same `Idempotency-Key`, with the signed credential in `Payment-Authorization: Payment ...` (or in `Authorization: Payment ...` when the management key is sent as `X-Api-Key`). A paid request answers `202`: the transfer was broadcast or the card was charged, and the payment is still being confirmed, so credits arrive asynchronously. Poll the URL in the `Location` header, `GET /api/v1/credits/purchases/{id}`, until `status` is `credited` or `failed`. operationId: createCreditsPurchases parameters: - description: >- Identifies the purchase. Send the same value on the unpaid request and on the paid retry; use a new value for a new purchase. in: header name: idempotency-key required: true schema: description: >- Identifies the purchase. Send the same value on the unpaid request and on the paid retry; use a new value for a new purchase. example: 6f1f7f0e-2b1a-4f57-9a43-3c1f6f3e8b0d maxLength: 255 minLength: 1 type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateCreditPurchaseRequest' required: true responses: '202': content: application/json: schema: $ref: '#/components/schemas/CreditPurchaseResponse' description: >- Payment accepted; credits are minted when the PaymentIntent succeeds. headers: Location: description: 'The purchase to poll: `GET /api/v1/credits/purchases/{id}`.' required: true schema: description: 'The purchase to poll: `GET /api/v1/credits/purchases/{id}`.' example: /api/v1/credits/purchases/pi_3PqXyZ2eZvKYlo2C0abc1234 type: string Payment-Receipt: description: >- The payment reference, on the request that paid: the Tempo transaction hash for USDC, or the PaymentIntent ID for a card. Absent when an earlier request already paid this purchase. required: false schema: description: >- The payment reference, on the request that paid: the Tempo transaction hash for USDC, or the PaymentIntent ID for a card. Absent when an earlier request already paid this purchase. example: >- 0x8f3c2b1a9e7d6c5b4a39281706f5e4d3c2b1a09f8e7d6c5b4a39281706f5e4d3 type: string '400': content: application/json: example: error: code: 400 message: Invalid request parameters schema: $ref: '#/components/schemas/BadRequestResponse' description: Bad Request - Invalid request parameters or malformed input '401': content: application/json: example: error: code: 401 message: Missing Authentication header schema: $ref: '#/components/schemas/UnauthorizedResponse' description: Unauthorized - Authentication required or invalid credentials '402': content: application/problem+json: schema: $ref: '#/components/schemas/CreditPurchasePaymentRequired' description: >- Payment required. An unpaid request carries the MPP challenge in `WWW-Authenticate`, and a `Link: rel="help"` header plus a `setup` field pointing at the agent setup guide, `GET /api/v1/credits/purchases/setup`. headers: Link: description: The agent setup guide. required: true schema: description: The agent setup guide. example: >- ; rel="help" type: string WWW-Authenticate: description: >- The MPP challenges, one per way to pay: `Payment id="...", method="tempo", intent="charge", ...` for USDC on Tempo and, when cards are offered, `Payment id="...", method="stripe", intent="charge", ...` for a card. Pay one of them. required: true schema: description: >- The MPP challenges, one per way to pay: `Payment id="...", method="tempo", intent="charge", ...` for USDC on Tempo and, when cards are offered, `Payment id="...", method="stripe", intent="charge", ...` for a card. Pay one of them. type: string '403': content: application/json: example: error: code: 403 message: Only management keys can perform this operation schema: $ref: '#/components/schemas/ForbiddenResponse' description: Forbidden - Authentication successful but insufficient permissions '404': content: application/json: example: error: code: 404 message: Resource not found schema: $ref: '#/components/schemas/NotFoundResponse' description: Not Found - Resource does not exist '409': content: application/json: example: error: code: 409 message: Resource conflict. Please try again later. schema: $ref: '#/components/schemas/ConflictResponse' description: Conflict - Resource conflict or concurrent modification '429': content: application/json: example: error: code: 429 message: Rate limit exceeded schema: $ref: '#/components/schemas/TooManyRequestsResponse' description: Too Many Requests - Rate limit exceeded '500': content: application/json: example: error: code: 500 message: Internal Server Error schema: $ref: '#/components/schemas/InternalServerResponse' description: Internal Server Error - Unexpected server error '503': content: application/json: schema: $ref: '#/components/schemas/CreditPurchaseUnavailableResponse' description: >- Temporarily unavailable, or the outcome of a paid request is unknown. When the outcome is unknown and the purchase is known, `Location` and `error.metadata.purchase_id` name the purchase: poll it before paying again. headers: Location: description: >- The purchase to poll: `GET /api/v1/credits/purchases/{id}`. Present when the outcome of a paid request is unknown and its purchase is known. required: false schema: description: >- The purchase to poll: `GET /api/v1/credits/purchases/{id}`. Present when the outcome of a paid request is unknown and its purchase is known. example: /api/v1/credits/purchases/pi_3PqXyZ2eZvKYlo2C0abc1234 type: string security: - bearerAuth: [] components: schemas: CreateCreditPurchaseRequest: properties: credit_amount_usd: description: >- Credits to buy, in USD with at most two decimals. The platform fee is added on top and shown in the challenge and the receipt. example: '25.00' type: string required: - credit_amount_usd type: object CreditPurchaseResponse: properties: data: $ref: '#/components/schemas/CreditPurchase' required: - data type: object BadRequestResponse: description: Bad Request - Invalid request parameters or malformed input example: error: code: 400 message: Invalid request parameters properties: error: $ref: '#/components/schemas/BadRequestResponseErrorData' openrouter_metadata: additionalProperties: {} type: - object - 'null' user_id: type: - string - 'null' required: - error type: object UnauthorizedResponse: description: Unauthorized - Authentication required or invalid credentials example: error: code: 401 message: Missing Authentication header properties: error: $ref: '#/components/schemas/UnauthorizedResponseErrorData' openrouter_metadata: additionalProperties: {} type: - object - 'null' user_id: type: - string - 'null' required: - error type: object CreditPurchasePaymentRequired: properties: challengeId: type: string detail: type: string setup: description: The agent setup guide, `GET /api/v1/credits/purchases/setup`. example: https://openrouter.ai/api/v1/credits/purchases/setup type: string status: enum: - 402 type: number title: type: string type: example: https://paymentauth.org/problems/payment-required type: string required: - type - title - status - setup type: object ForbiddenResponse: description: Forbidden - Authentication successful but insufficient permissions example: error: code: 403 message: Only management keys can perform this operation properties: error: $ref: '#/components/schemas/ForbiddenResponseErrorData' openrouter_metadata: additionalProperties: {} type: - object - 'null' user_id: type: - string - 'null' required: - error type: object NotFoundResponse: description: Not Found - Resource does not exist example: error: code: 404 message: Resource not found properties: error: $ref: '#/components/schemas/NotFoundResponseErrorData' openrouter_metadata: additionalProperties: {} type: - object - 'null' user_id: type: - string - 'null' required: - error type: object ConflictResponse: description: Conflict - Resource conflict or concurrent modification example: error: code: 409 message: Resource conflict. Please try again later. properties: error: $ref: '#/components/schemas/ConflictResponseErrorData' openrouter_metadata: additionalProperties: {} type: - object - 'null' user_id: type: - string - 'null' required: - error type: object TooManyRequestsResponse: description: Too Many Requests - Rate limit exceeded example: error: code: 429 message: Rate limit exceeded properties: error: $ref: '#/components/schemas/TooManyRequestsResponseErrorData' openrouter_metadata: additionalProperties: {} type: - object - 'null' user_id: type: - string - 'null' required: - error type: object InternalServerResponse: description: Internal Server Error - Unexpected server error example: error: code: 500 message: Internal Server Error properties: error: $ref: '#/components/schemas/InternalServerResponseErrorData' openrouter_metadata: additionalProperties: {} type: - object - 'null' user_id: type: - string - 'null' required: - error type: object CreditPurchaseUnavailableResponse: example: error: code: 503 message: >- The payment transfer could not be confirmed; poll the purchase before retrying metadata: purchase_id: pi_3PqXyZ2eZvKYlo2C0abc1234 properties: error: properties: code: type: integer message: type: string metadata: description: >- Present when the outcome of a paid request is unknown and its purchase is known. properties: purchase_id: description: >- The purchase to poll with `GET /api/v1/credits/purchases/{id}` before paying again. example: pi_3PqXyZ2eZvKYlo2C0abc1234 type: string required: - purchase_id type: object required: - code - message type: object required: - error type: object CreditPurchase: properties: created_at: type: string credit_amount_usd: type: string failure_reason: type: - string - 'null' id: description: Purchase id, the Stripe PaymentIntent that owns the deposit address. type: string network: type: string platform_fee_usd: type: string protocol: type: string status: enum: - awaiting_payment - processing - credited - failed type: string total_charged_usd: type: string required: - id - status - credit_amount_usd - platform_fee_usd - total_charged_usd - protocol - network - failure_reason - created_at type: object BadRequestResponseErrorData: description: Error data for BadRequestResponse example: code: 400 message: Invalid request parameters properties: code: type: integer message: type: string metadata: additionalProperties: {} type: - object - 'null' required: - code - message type: object UnauthorizedResponseErrorData: description: Error data for UnauthorizedResponse example: code: 401 message: Missing Authentication header properties: code: type: integer message: type: string metadata: additionalProperties: {} type: - object - 'null' required: - code - message type: object ForbiddenResponseErrorData: description: Error data for ForbiddenResponse example: code: 403 message: Only management keys can perform this operation properties: code: type: integer message: type: string metadata: additionalProperties: {} type: - object - 'null' required: - code - message type: object NotFoundResponseErrorData: description: Error data for NotFoundResponse example: code: 404 message: Resource not found properties: code: type: integer message: type: string metadata: additionalProperties: {} type: - object - 'null' required: - code - message type: object ConflictResponseErrorData: description: Error data for ConflictResponse example: code: 409 message: Resource conflict. Please try again later. properties: code: type: integer message: type: string metadata: additionalProperties: {} type: - object - 'null' required: - code - message type: object TooManyRequestsResponseErrorData: description: Error data for TooManyRequestsResponse example: code: 429 message: Rate limit exceeded properties: code: type: integer message: type: string metadata: additionalProperties: {} type: - object - 'null' required: - code - message type: object InternalServerResponseErrorData: description: Error data for InternalServerResponse example: code: 500 message: Internal Server Error properties: code: type: integer message: type: string metadata: additionalProperties: {} type: - object - 'null' required: - code - message type: object securitySchemes: apiKey: description: API key as bearer token in Authorization header scheme: bearer type: http ````