Agent Payment API

Introduction

The Agent Payment API allows an AI agent to autonomously manage and purchase API credits on behalf of a user. This enables unattended workflows where the agent can check its remaining credit balance, review spending limits, and top up credits via the user's saved Stripe payment method all without human intervention.

All three endpoints are hosted on payments.builtwith.com and authenticate with your BuiltWith API key.

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.

Authentication

Pass the Agent API Key using either method below. The KEY query parameter takes priority if both are supplied.

Authorization Header (recommended)

Authorization: Bearer 00000000-0000-0000-0000-000000000000

Query Parameter (fallback)

?KEY=00000000-0000-0000-0000-000000000000

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 Payment API support to my app. Check the current API credit balance,
and if below 1000 credits, purchase 2000 more using the Agent Payment API.

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?KEY=00000000-0000-0000-0000-000000000000

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?KEY=00000000-0000-0000-0000-000000000000

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 across the current 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 Agent API Key as the Authorization: Bearer header or as a ?KEY= query parameter. The request body must be JSON.

Request Body

Field	Type	Required	Description
`credits`	`number`	Yes	Number of credits to purchase. Minimum 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 Body

{ "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 - credits below 2,000, exceeds per-purchase limit, or monthly limit would be breached.
401	Missing or invalid Agent API Key.
402	Stripe payment failed or no chargeable payment method on file.
403	Account billing suspended.
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.