---
title: "Buy credits over the Machine Payments Protocol (MPP): an agent pays with no checkout page"
method: POST
path: "/api/v1/credits"
tags: ["credits"]
---

# Buy credits over the Machine Payments Protocol (MPP): an agent pays with no checkout page

`POST /api/v1/credits`

## Request

- Base URL: `https://www.orgo.ai`
- URL: `https://www.orgo.ai/api/v1/credits`
- Auth: HTTP bearer

Two requests, per MPP (https://mpp.dev). First send the body with your API key and no payment: the answer is `402` with one `WWW-Authenticate: Payment ...` challenge per way to pay (`method="stripe"`: a Stripe Shared Payment Token from a card or Link wallet; `method="tempo"`: USDC on Tempo, where offered). Pay one challenge and send the SAME request again with the credential in `Payment-Authorization: Payment <credential>` (your `Authorization: Bearer` key stays as it is). A challenge is signed by Orgo, bound to your account and this amount, and expires in 5 minutes; a credential is accepted once. MPP clients do this for you: `npx mppx <url> -H "Authorization: Bearer $ORGO_API_KEY" -J '{"amount_usd":10}'`, or `fetch` patched by `Mppx.create({ methods: [...] })` from `mppx/client`.

Credits are added to the account that owns the key, one dollar of credit per dollar paid. Account-wide keys and signed-in sessions only. Over the limit of 20 requests a minute per key the answer is 429.

Not every environment takes MPP: where it is off the answer is 503 `mpp_off`. A person can then buy credit from a Checkout link: `POST /api/credits/checkout {"amount_cents": 1000}` answers its `url`.

## Headers

- `Payment-Authorization` string

## Request body

- object
  - `amount_usd` number, required: Dollars of credit to buy, at most 2 decimals.

## Response `200`

Paid and credited. The `Payment-Receipt` header carries the MPP receipt.

- object
  - `credited_usd` number, required
  - `balance_usd` number, nullable, required: The account’s credit balance after this top-up.
  - `receipt` object, required
    - `method` 'stripe' | 'tempo'
    - `reference` string: The Stripe PaymentIntent (pi_...) for a card, the transaction hash for Tempo.
  - `duplicate` boolean: True when this payment had already been credited. Nothing was added again.

## Other responses

- `202`: Paid, but the credit could not be written just now (credit_pending). It is added shortly; do not pay again.
- `400`: invalid_amount or invalid_json.
- `401`: Unauthenticated.
- `402`: Payment required: no credential, or one that was refused (expired, used, for another account or amount). Pay a challenge from `WWW-Authenticate` and retry. A refused credential also carries an `application/problem+json` body.
- `403`: A workspace-scoped key (account_key_required) or a guest (account_required).
- `429`: Rate limited (rate_limited). See Retry-After.
- `503`: MPP is off in this environment (mpp_off). Use POST /api/credits/checkout for a Checkout link instead.

## Changes

- **2026-11-01** `60e768a2bb9d`: 9 info
  - added the optional property `docs_url` to the response with the `400` status
  - added the optional property `docs_url` to the response with the `403` status
  - added the optional property `docs_url` to the response with the `503` status
  - added the optional property `next` to the response with the `400` status
  - …5 more
- **2026-10-13** `ad4a47ee52a8`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/orgo/apis/orgo-api/changes/api/v1/credits/post.md)

---

[API](https://skmtc.dev/orgo/apis/orgo-api.md) - [All operations](https://skmtc.dev/orgo/apis/orgo-api/llms.txt) - [OpenAPI document](https://skmtc.dev/orgo/apis/orgo-api/revisions/e4c1e7379fa5?raw)