Agent Stripe Credit Top-Up API

Introduction

The Agent Stripe Credit Top-Up API lets an AI agent check an account's API-credit balance and, within user-configured limits, charge the account's saved Stripe payment method to add more account credits.

This API is not x402. It requires an existing BuiltWith account and separately scoped Agent Billing Key. For accountless Base USDC payments, use the BuiltWith x402 payments page.

All three primary endpoints are hosted on payments.builtwith.com.

Before an agent can use these endpoints the user must enable Agent API Billing and configure spending limits at https://payments.builtwith.com/agent-payment-api-config.

After manual enablement, agents can use legacy mppx path aliases for the same Stripe top-up operations at https://api.builtwith.com/mppx. The aliases are not an x402 or payment-challenge protocol.

Authentication

Copy the separately scoped Agent Billing Key from the billing configuration page and send it in the Authorization header. General BuiltWith API keys and temporary bw- device tokens cannot purchase credits.

Authorization: Bearer YOUR_AGENT_BILLING_KEY

The legacy KEY query parameter is deprecated because credentials in URLs can be retained in logs and browser history.

Requests with a missing, invalid, or disabled key return HTTP 401. Accounts with billing suspended return HTTP 403.

🤖 AI Agent Prompt

Reference https://api.builtwith.com/llms.txt and
https://raw.githubusercontent.com/builtwith/builtwith-ai-sdk/refs/heads/main/README.md
Add BuiltWith Agent Stripe Credit Top-Up API support to my app. This is saved-card
account billing, not x402. Check the account API-credit balance and, if below 1000,
purchase 2000 more using a unique Idempotency-Key and the scoped Agent Billing Key.
If the legacy mppx path aliases are desired, use
https://api.builtwith.com/mppx/openapi.json and the Agent Payment API routes
https://api.builtwith.com/mppx/api-discovery,
https://api.builtwith.com/mppx/api-configuration, and
https://api.builtwith.com/mppx/api-purchase.

mppx Stripe Credit Top-Up Path Aliases

These legacy mppx paths proxy the saved-Stripe-method credit top-up API. They are not x402 and do not return or accept payment-challenge headers.

Discovery

GET https://api.builtwith.com/mppx/openapi.json

Routes

GET https://api.builtwith.com/mppx/api-discovery

GET https://api.builtwith.com/mppx/api-configuration

POST https://api.builtwith.com/mppx/api-purchase

{ "credits": 2000 }

Send the scoped Agent Billing Key in Authorization: Bearer and include a unique Idempotency-Key on purchases.

GET /v1/billing/api-discovery — Credit Balance

Returns the current API credit balance for the account.

Request

GET https://payments.builtwith.com/v1/billing/api-discovery
Authorization: Bearer YOUR_AGENT_BILLING_KEY

Response Fields

Field	Type	Description
`credits_total`	`number`	Total credits ever allocated to the account.
`credits_used`	`number`	Credits consumed by API calls to date.
`credits_available`	`number`	Remaining usable credits (total minus used). This is what the agent should check before making API calls.

Example Response

{
  "credits_total": 10000,
  "credits_used": 1234,
  "credits_available": 8766
}

GET /v1/billing/api-configuration — Spending Limits

Returns the configured spending limits and how much of the monthly allowance has already been used. The agent should check this before attempting a purchase to avoid rejected requests.

Request

GET https://payments.builtwith.com/v1/billing/api-configuration
Authorization: Bearer YOUR_AGENT_BILLING_KEY

Response Fields

Field	Type	Description
`max_per_purchase`	`number`	Maximum credits the agent may buy in a single transaction.
`max_monthly`	`number`	Maximum credits the agent may purchase during the current UTC calendar month.
`monthly_purchased`	`number`	Credits already purchased by the agent this calendar month.
`monthly_remaining`	`number`	How many more credits can be purchased this month before the monthly limit is reached.
`cost_per_2000_credits_usd`	`number`	USD cost for the minimum 2,000-credit purchase. Use this to estimate the cost of a planned purchase.

Example Response

{
  "max_per_purchase": 5000,
  "max_monthly": 20000,
  "monthly_purchased": 5000,
  "monthly_remaining": 15000,
  "cost_per_2000_credits_usd": 99.00
}

POST /v1/billing/api-purchase — Buy Credits

Charges the user's saved Stripe payment method and immediately credits the account. The purchase is subject to the per-purchase and monthly limits set in the Agent API Billing configuration.

Request

POST https://payments.builtwith.com/v1/billing/api-purchase

Send the scoped Agent Billing Key as Authorization: Bearer YOUR_AGENT_BILLING_KEY, and send a unique Idempotency-Key. Reuse that key only when retrying the identical purchase.

Request Body

Field	Type	Required	Description
`credits`	`number`	Yes	Number of credits to purchase in fixed increments of 2,000. Must not exceed `max_per_purchase` or the remaining monthly allowance.

Success Response (HTTP 200)

Field	Type	Description
`success`	`boolean`	`true`
`credits_purchased`	`number`	Credits added to the account.
`cost_usd`	`number`	Amount charged in USD.
`payment_id`	`string`	Stripe PaymentIntent ID for reconciliation.
`credits_available`	`number`	Updated available credit balance after the purchase.

Example Request

Authorization: Bearer YOUR_AGENT_BILLING_KEY
Idempotency-Key: 72b7b97c-3b6d-4c64-9bbf-20fd2a931514
Content-Type: application/json

{ "credits": 2000 }

Example Success Response

{
  "success": true,
  "credits_purchased": 2000,
  "cost_usd": 99.00,
  "payment_id": "pi_3abc123xyz",
  "credits_available": 10766
}

Error Responses

HTTP	Meaning
400	Validation failure - missing idempotency key, credits not in 2,000 increments, per-purchase limit exceeded, or UTC monthly limit breached.
401	Missing or invalid Agent Billing Key. Includes a WWW-Authenticate challenge.
402	Stripe payment failed or no chargeable payment method on file.
403	A broad API key was supplied instead of the scoped billing key, or account billing is suspended.
409	Idempotency key is still in progress or was previously used with different input.
405	Method not allowed - endpoint requires POST.

Special Domains

We maintain two lists of use for you when looking up domains. Ignore lists and BuiltWith Suffix lists.

Ignore List
This is our own internal list of domains we do not index. They are either blocked, contains too many misleading technologies or too many subdomains with user generated content.

BuiltWith Suffix List
This is based on the Public Suffix List but includes many additional entries for companies with subdomains that should be considered top level domains. This list provides us with better visibility for internal websites for example it brings northernbeaches.nsw.gov.au to the top level over nsw.gov.au.

Ignore Domains (XML, JSON or TXT)

https://api.builtwith.com/ignoresv1/api.json

Suffix Domains (XML, JSON or TXT)

https://api.builtwith.com/suffixv1/api.json

Error Codes

Note error messages in this format cannot be guaranteed, your implementation should also consider non-200 response codes as errors. The Lookup property will be null (json) or not provided (xml) if the error is server related. View all potential well-formed error codes.

Our standard terms cover the use all of our APIs.

In general, you can use the API to enhance your product in many ways. The only limitation is you cannot resell the data as-is or provide duplicate functionality to builtwith.com and its associated services.