> For the complete documentation index, see [llms.txt](https://docs.lightningrod.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.lightningrod.ai/api-reference/agentic-payments.md).

# Agentic Payments

## Add credits via MPP (Machine Payments Protocol)

> Pay via MPP to add credits and obtain (or refresh) an API key, then call the standard \`/v1/openai/\*\` endpoints with it as a \`Bearer\` token.\
> \
> \*\*Payment rails:\*\* every challenge offers both, as two separate \`WWW-Authenticate\` header instances. Pay whichever one you can and retry with that rail's credential:\
> \
> \- \*\*Stripe\*\* (\`method="stripe"\`): pay with a Stripe card or Link Shared Payment Token. Retry with \`Authorization: Payment \<stripe-credential>\`.\
> \
> \- \*\*Tempo\*\* (\`method="tempo"\`): pay with on-chain USDC on the Tempo network. Retry with \`Authorization: Payment \<tempo-credential>\`.\
> \
> \*\*Amount:\*\* defaults to $5.00; pass \`amount\_cents\` to choose a size (clamped to the credit-purchase limits). Send the \*\*same\*\* \`amount\_cents\` on the paid retry as on the challenge call.\
> \
> \*\*Headers:\*\*\
> \- \`Authorization: Payment \<credential>\` — the MPP payment credential.\
> \- \`X-API-Key: sk\_…\` \*(optional)\* — refill an existing org; omit to mint a new org + key (returned once in the response body).

```json
{"openapi":"3.1.0","info":{"title":"LightningRod API","version":"1.0.0"},"servers":[{"url":"https://api.lightningrod.ai"}],"paths":{"/v1/mpp/topup":{"post":{"tags":["Agentic Payments"],"summary":"Add credits via MPP (Machine Payments Protocol)","description":"Pay via MPP to add credits and obtain (or refresh) an API key, then call the standard `/v1/openai/*` endpoints with it as a `Bearer` token.\n\n**Payment rails:** every challenge offers both, as two separate `WWW-Authenticate` header instances. Pay whichever one you can and retry with that rail's credential:\n\n- **Stripe** (`method=\"stripe\"`): pay with a Stripe card or Link Shared Payment Token. Retry with `Authorization: Payment <stripe-credential>`.\n\n- **Tempo** (`method=\"tempo\"`): pay with on-chain USDC on the Tempo network. Retry with `Authorization: Payment <tempo-credential>`.\n\n**Amount:** defaults to $5.00; pass `amount_cents` to choose a size (clamped to the credit-purchase limits). Send the **same** `amount_cents` on the paid retry as on the challenge call.\n\n**Headers:**\n- `Authorization: Payment <credential>` — the MPP payment credential.\n- `X-API-Key: sk_…` *(optional)* — refill an existing org; omit to mint a new org + key (returned once in the response body).","operationId":"mpp_topup","requestBody":{"content":{"application/json":{"schema":{"type":"object","title":"MppTopupRequest","properties":{"amount_cents":{"type":"integer","title":"Amount Cents","description":"Top-up size in cents. Defaults to 500 ($5.00). Range $1.00–$10,000.00. Must be identical on the challenge call and the paid retry.","default":500,"minimum":100,"maximum":1000000}},"additionalProperties":false}}},"required":false},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MppTopupResponse"}}}},"402":{"description":"Payment required. Two `WWW-Authenticate: Payment` header instances are returned, one per supported rail (`method=\"stripe\"` and `method=\"tempo\"`), each quoting the top-up amount; pay either and retry.","headers":{"WWW-Authenticate":{"description":"MPP Payment challenge (scheme `Payment`). Sent once per each supported payment rail.","schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"MppTopupResponse":{"properties":{"organization_id":{"type":"string","title":"Organization Id"},"credited_cents":{"type":"integer","title":"Credited Cents"},"api_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"},"api_key_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key Id"}},"type":"object","required":["organization_id","credited_cents"],"title":"MppTopupResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}
```