API per la ricarica del credito tramite Stripe

Introduzione

L'API Agent Stripe Credit Top-Up consente a un agente AI di verificare il saldo del credito API di un account e, entro i limiti configurati dall'utente, di addebitare sul metodo di pagamento Stripe salvato nell'account per aggiungere ulteriore credito.

Questa API non è x402. Richiede un account BuiltWith esistente e una chiave di fatturazione agente con ambito separato. Per i pagamenti Base USDC senza account, utilizzare BuiltWith x402 payments page.

Tutti e tre gli endpoint primari sono ospitati su payments.builtwith.com.

Prima che un agente possa utilizzare questi endpoint, l'utente deve abilitare la fatturazione API dell'agente e configurare i limiti di spesa su https://payments.builtwith.com/agent-payment-api-config.

Dopo l'abilitazione manuale, gli agenti possono utilizzare gli alias di percorso mppx legacy per le stesse operazioni di ricarica Stripe a https://api.builtwith.com/mppx. Gli alias non costituiscono un protocollo x402 o di contestazione del pagamento.

Autenticazione

Copia la chiave di fatturazione dell'agente con ambito separato dalla pagina di configurazione della fatturazione e inviala nell'intestazione di autorizzazione. Le chiavi API BuiltWith generiche e i token temporanei del dispositivo bw- non possono acquistare crediti.

Authorization: Bearer YOUR_AGENT_BILLING_KEY

Il parametro di query KEY, ormai obsoleto, è deprecato perché le credenziali presenti negli URL possono essere memorizzate nei log e nella cronologia del browser.

Le richieste con una chiave mancante, non valida o disabilitata restituiscono HTTP 401. Gli account con fatturazione sospesa restituiscono HTTP 403.

🤖 Richiesta dell'agente AI

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

Questi percorsi mppx legacy fungono da proxy per l'API di ricarica del credito con metodo Stripe salvato. Non sono x402 e non restituiscono né accettano intestazioni di sfida al pagamento.

Scoperta

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

Percorsi

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 }

Invia la chiave di fatturazione dell'agente con ambito in Autorizzazione: Portatore e includi una chiave di idempotenza univoca negli acquisti.

GET /v1/billing/api-discovery — Saldo a credito

Restituisce il saldo corrente del credito API per l'account.

Richiesta

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

Campi di risposta

Campo	Tipo	Descrizione
`credits_total`	`number`	Totale dei crediti mai accreditati sul conto.
`credits_used`	`number`	Crediti consumati dalle chiamate API fino ad oggi.
`credits_available`	`number`	Crediti utilizzabili rimanenti (totale meno utilizzati). Questo è ciò che l'agente dovrebbe verificare prima di effettuare chiamate API.

Esempio di risposta

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

GET /v1/billing/api-configuration — Limiti di spesa

Restituisce i limiti di spesa configurati e la percentuale del budget mensile già utilizzata. L'operatore dovrebbe verificare queste informazioni prima di tentare un acquisto per evitare che le richieste vengano rifiutate.

Richiesta

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

Campi di risposta

Campo	Tipo	Descrizione
`max_per_purchase`	`number`	Numero massimo di crediti che l'agente può acquistare in una singola transazione.
`max_monthly`	`number`	Numero massimo di crediti che l'agente può acquistare durante il mese di calendario UTC corrente.
`monthly_purchased`	`number`	Crediti già acquistati dall'agente in questo mese solare.
`monthly_remaining`	`number`	Quanti altri crediti è possibile acquistare questo mese prima di raggiungere il limite mensile?
`cost_per_2000_credits_usd`	`number`	Costo in USD per un acquisto minimo di 2.000 crediti. Utilizza questo dato per stimare il costo di un acquisto pianificato.

Esempio di risposta

{
  "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 — Acquista crediti

Addebita l'importo sul metodo di pagamento Stripe salvato dall'utente e lo accredita immediatamente sul conto. L'acquisto è soggetto ai limiti per singolo acquisto e mensili impostati nella configurazione di fatturazione dell'API dell'agente.

Richiesta

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

Invia la chiave di fatturazione dell'agente con ambito come Authorization: Bearer YOUR_AGENT_BILLING_KEY, e inviare un unico Idempotency-Key. Riutilizza quella chiave solo quando tenti di ripetere lo stesso acquisto.

Corpo della richiesta

Campo	Tipo	Necessario	Descrizione
`credits`	`number`	SÌ	Numero di crediti da acquistare in incrementi fissi di 2.000. Non deve superare `max_per_purchase` o l'indennità mensile rimanente.

Risposta di successo (HTTP 200)

Campo	Tipo	Descrizione
`success`	`boolean`	`true`
`credits_purchased`	`number`	Crediti aggiunti all'account.
`cost_usd`	`number`	Importo addebitato in USD.
`payment_id`	`string`	ID di Stripe PaymentIntent per la riconciliazione.
`credits_available`	`number`	Saldo del credito disponibile aggiornato dopo l'acquisto.

Esempio di richiesta

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

{ "credits": 2000 }

Esempio di risposta positiva

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

Risposte di errore

HTTP	Senso
400	Errore di convalida: chiave di idempotenza mancante, crediti non in incrementi di 2.000, limite per acquisto superato o limite mensile UTC violato.
401	Chiave di fatturazione dell'agente mancante o non valida. Include una verifica WWW-Authenticate.
402	Il pagamento tramite Stripe non è andato a buon fine oppure non è presente alcun metodo di pagamento valido nei nostri archivi.
403	È stata fornita una chiave API generica anziché la chiave di fatturazione specifica, oppure la fatturazione dell'account è sospesa.
409	La chiave di idempotenza è ancora in fase di elaborazione oppure è stata precedentemente utilizzata con input diversi.
405	Metodo non consentito: l'endpoint richiede il metodo POST.

Domini speciali

Manteniamo due elenchi utili per la ricerca di domini: gli elenchi "Ignora" e gli elenchi "BuiltWith Suffix".

Elenco ignorati
TQuesto è il nostro elenco interno di domini che non indicizziamo. Sono bloccati, contengono troppe tecnologie fuorvianti o troppi sottodomini con contenuti generati dagli utenti.

BuiltWith Elenco dei suffissi
Questo si basa sul Elenco dei suffissi pubblici ma include molte voci aggiuntive per le aziende con sottodomini che dovrebbero essere considerati domini di primo livello. Questo elenco ci garantisce una migliore visibilità per i siti web interni, ad esempio porta northernbeaches.nsw.gov.au al primo posto rispetto a nsw.gov.au.

Ignora domini (XML, JSON or TXT)

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

Domini suffissi (XML, JSON or TXT)

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

Codici di errore

Si noti che i messaggi di errore in questo formato non possono essere garantiti; l'implementazione dovrebbe considerare anche i codici di risposta diversi da 200 come errori. La proprietà Lookup sarà null (json) o non fornita (xml) se l'errore è correlato al server. Visualizza tutti i potenziali codici di errore ben formati.

Termini di utilizzo

Nostro termini standard coprono l'utilizzo di tutte le nostre API.

In generale, puoi utilizzare l'API per migliorare il tuo prodotto in molti modi. L'unica limitazione è che non puoi rivendere i dati così come sono o fornire funzionalità duplicate a builtwith.com e ai suoi servizi associati.