Paga una richiesta di pagamento x402 Paga una sfida MPP Integrazioni con il framework

Elaborare un pagamento

Per elaborare un pagamento, hai bisogno di due risorse:

Strumento di pagamento: un portafoglio crittografico integrato con Coinbase o Stripe. Vedi Creare uno strumento di pagamento.
Sessione di pagamento: una sessione limitata nel tempo che, facoltativamente, impone un budget di spesa. Vedi Creare una sessione di pagamento.

Dopo che entrambi esistono, chiama ProcessPayment con l'ID della sessione di pagamento, l'ID dello strumento di pagamento e un payload di pagamento. Il servizio convalida la richiesta, controlla il budget, firma la transazione sulla blockchain appropriata e restituisce un risultato di pagamento firmato. Per lo schema completo di richiesta e risposta, consulta ProcessPayment l'API Reference.

AgentCore payments supporta due protocolli di pagamento, che puoi selezionare con il paymentType parametro:

CRYPTO_X402— Il protocollo x402. Fornisci il payload di pagamento x402 del commerciante e l'agente riprova la richiesta con la prova firmata nell'intestazione. paymentInput.cryptoX402 X-PAYMENT
MPP— Il Machine Payments Protocol (MPP). Inoltra la richiesta del commerciante e paymentInput.mpp l'agente WWW-Authenticate: Payment riprova la richiesta con le credenziali restituite nell'intestazione. Authorization

Scegli paymentType quello che corrisponde al protocollo utilizzato dal commerciante nella risposta. 402 Payment Required Per i dettagli della richiesta e della risposta x402, vedi Pagare una richiesta di pagamento x402. Per i dettagli su richieste e risposte MPP, vedi Pay an MPP challenge.

Suggerimento

Puoi automatizzare i passaggi in questa pagina con l'abilità AgentCore Pagamenti nel toolkit per agenti. AWS L'abilità fa parte del plug-in aws-agents e consente a un agente di codifica AI di creare il Payment Manager, il connettore, il fornitore di credenziali, lo strumento di pagamento e la sessione utilizzando la agentcore CLI e aggiungere uno strumento di elaborazione dei pagamenti all'agente. Per i dettagli, consulta il quickstart e il toolkit per gli agenti attivi. AWS GitHub

Esistono cinque modi per richiamare l'API: ProcessPayment

Esempio

AgentCore CLI

Se il tuo agente è installato con funzionalità di pagamento configurate, richiamalo con payment context e l'interceptor x402 gestirà automaticamente l'elaborazione dei pagamenti:


agentcore invoke \
  --prompt "Access the premium endpoint at https://example-x402-merchant.com/paid-api" \
  --payment-instrument-id <INSTRUMENT_ID> \
  --auto-session \
  --payment-user-id user@example.com

Per utilizzare una sessione esplicita anziché crearne una automatica:


agentcore invoke \
  --prompt "Access the premium endpoint at https://example-x402-merchant.com/paid-api" \
  --payment-instrument-id <INSTRUMENT_ID> \
  --payment-session-id <SESSION_ID> \
  --payment-user-id user@example.com

Il plug-in x402 dell'agente distribuito intercetta le risposte e le chiamate ProcessPayment HTTP 402 e riprova la richiesta con una prova. AgentCore Richiede CLI v0.19.0 o successivo.

AgentCore SDK

Utilizza la PaymentManager classe per generare manualmente le intestazioni di pagamento all'interno di qualsiasi framework di agenti:


import uuid
from bedrock_agentcore.payments import PaymentManager

manager = PaymentManager(
    payment_manager_arn=mgr["paymentManagerArn"],
    region_name="us-west-2"
)

# When you receive a 402 response, generate payment proof
payment_required_request = {
    "statusCode": 402,
    "headers": payment_required["headers"],
    "body": payment_required["body"],
}
payment_proof_headers = manager.generate_payment_header(
    user_id="test-user-123",
    payment_instrument_id=instrument["paymentInstrumentId"],
    payment_session_id=session["paymentSessionId"],
    payment_required_request=payment_required_request,
    client_token=str(uuid.uuid4()),
)

payment_proof_headerscontiene l'intestazione della prova di pagamento. Includi questa intestazione quando ritenti la richiesta all'endpoint a pagamento. Puoi anche chiamare il process_payment metodo of PaymentManager per un maggiore controllo sugli input.

AWS CLI

L'esempio seguente elabora un pagamento x402 inoltrando il payload del commerciante: paymentInput.cryptoX402


aws bedrock-agentcore process-payment \
    --payment-manager-arn "arn:aws:bedrock-agentcore:us-west-2:123456789012:payment-manager/my-manager" \
    --payment-session-id "payment-session-abc123" \
    --payment-instrument-id "payment-instrument-xyz789" \
    --payment-type "CRYPTO_X402" \
    --payment-input '{
        "cryptoX402": {
            "version": "2",
            "payload": {
                "scheme": "exact",
                "network": "eip155:84532",
                "amount": "100000",
                "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
                "payTo": "0x99935f281d3ED1E804bF1413b76E0B03e1fed4F9",
                "maxTimeoutSeconds": 300,
                "extra": {"name": "USDC", "version": "2"}
            }
        }
    }' \
    --client-token "$(uuidgen)" \
    --region us-west-2

Per informazioni su come creare il protocollo paymentInput per ogni protocollo, incluso l'esempio dell'interfaccia a riga di comando MPPAWS, vedi Pay an x402 payment request e Pay an MPP challenge. Paga una sfida MPP

AWS SDK

L'esempio seguente elabora un pagamento x402 process_payment chiamando con il payload del commerciante: paymentInput.cryptoX402


import uuid

payment = dp_client.process_payment(
    userId="test-user-123",
    paymentManagerArn=PAYMENT_MANAGER_ARN,
    paymentSessionId=SESSION_ID,
    paymentInstrumentId=INSTRUMENT_ID,
    paymentType="CRYPTO_X402",
    paymentInput={
        "cryptoX402": {
            "version": "2",
            "payload": {
                "scheme": "exact",
                "network": "eip155:84532",
                "amount": "100000",
                "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
                "payTo": "0x99935f281d3ED1E804bF1413b76E0B03e1fed4F9",
                "maxTimeoutSeconds": 300,
                "extra": {"name": "USDC", "version": "2"},
            },
        }
    },
    clientToken=str(uuid.uuid4()),
)

Risposta:


{
    "processPaymentId": "12345678-1234-1234-1234-123456789012",
    "paymentManagerArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:payment-manager/my-manager-a1b2c3d4e5",
    "paymentSessionId": "payment-session-abc123def4567",
    "paymentInstrumentId": "payment-instrument-xyz789abc1234",
    "paymentType": "CRYPTO_X402",
    "status": "PROOF_GENERATED",
    "paymentOutput": {
        "cryptoX402": {
            "version": "2",
            "payload": {
                "...signed transaction proof..."
            }
        }
    },
    "createdAt": "2025-07-15T10:35:00Z",
    "updatedAt": "2025-07-15T10:35:02Z"
}

Una o status PROOF_GENERATED indica che la transazione è stata firmata e la prova di pagamento è inclusa. paymentOutput

Per informazioni su come creare il protocollo paymentInput per ogni protocollo, incluso l'esempio dell'AWSSDK MPP e la relativa risposta, vedi Pay an x402 payment request e Pay an MPP challenge.

Strands SDK

Il plug-in per AgentCore i pagamenti fornisce l'elaborazione automatica dei pagamenti per gli agenti di Strands. Supporta il protocollo x402 Payment Required, che consente agli agenti di gestire automaticamente le risposte HTTP 402.

Installation (Installazione):


pip install 'bedrock-agentcore[strands-agents]'

Configura e usa il plugin:


from strands import Agent
from strands_tools import http_request
from bedrock_agentcore.payments.integrations.config import AgentCorePaymentsPluginConfig
from bedrock_agentcore.payments.integrations.strands.plugin import AgentCorePaymentsPlugin

# Configure the plugin
config = AgentCorePaymentsPluginConfig(
    payment_manager_arn="arn:aws:bedrock-agentcore:us-west-2:123456789012:payment-manager/pm-abc123",
    user_id="test-user-123",
    payment_instrument_id="payment-instrument-XJU4RSQP9VO0ler",
    payment_session_id="payment-session-xuzrnUCd7RT725G",
    region="us-west-2",
)

# Create the plugin
plugin = AgentCorePaymentsPlugin(config=config)

# Create agent with the plugin
agent = Agent(
    system_prompt="You are a helpful assistant that can access paid APIs.",
    tools=[http_request],
    plugins=[plugin],
)

# Use the agent -- 402 responses are automatically handled
agent("access https://drvd12nxpcyd5.cloudfront.net/market-recap")

Il plug-in per AgentCore i pagamenti intercetta automaticamente le richieste di pagamento x402, elabora il pagamento e riprova la richiesta con la prova di pagamento per l'agente.

LangGraph

Il middleware per AgentCore i pagamenti fornisce l'elaborazione automatica dei pagamenti per gli agenti. LangGraph Supporta il protocollo x402 Payment Required, che consente agli agenti di gestire automaticamente le risposte HTTP 402.

Installation (Installazione):


pip install 'bedrock-agentcore[langgraph]'

Configura e usa il middleware:


from langchain.agents import create_agent
from bedrock_agentcore.payments.integrations.langgraph import (
    AgentCorePaymentsConfig,
    AgentCorePaymentsMiddleware,
)

config = AgentCorePaymentsConfig(
    payment_manager_arn="arn:aws:bedrock-agentcore:us-west-2:123456789012:payment-manager/pm-abc123",
    user_id="test-user-123",
    payment_instrument_id="payment-instrument-XJU4RSQP9VO0ler",
    region="us-west-2",
    auto_session=True,
)

payments = AgentCorePaymentsMiddleware(config)

agent = create_agent(
    model="us.anthropic.claude-sonnet-4-20250514-v1:0",
    tools=[],
    middleware=[payments],
)

result = agent.invoke({"messages": [{"role": "user", "content": "access https://drvd12nxpcyd5.cloudfront.net/market-recap"}]})
print(result)

Il middleware per AgentCore i pagamenti intercetta automaticamente le richieste di pagamento x402, elabora il pagamento e riprova la richiesta con la prova di pagamento per l'agente.

Paga una richiesta di pagamento x402

Quando un commerciante risponde inserendo nella sua 402 Payment Required risposta un payload x402, tu inoltri tale payload ai AgentCore pagamenti, e Payments restituisce una prova firmata. AgentCore Copi il payload del commerciante in e AgentCore Payments controlla il budgetpaymentInput.cryptoX402, firma la transazione con il portafoglio e restituisce la ricevuta firmata. Alleghi la bozza all'X-PAYMENTintestazione e ritenti la richiesta originale.

Richiesta e risposta

Fornisci i seguenti campi in: paymentInput.cryptoX402

version— La versione del protocollo x402 (ad esempio, 1 o2). Obbligatorio.
payload— I requisiti di pagamento x402 del commerciante, trasmessi come oggetto JSON. Specifica i campischeme,, network maxAmountRequired assetpayTo, e altri campi della risposta del commerciante. 402 Obbligatorio.
permit2AllowanceLimit— L'indennità Permit2 massima concessa in catena, nella denominazione più piccola dell'asset. Opzionale. Impostatela solo per lo schema upto (a pagamento), che viene regolato tramite il contratto Permit2; fornirla per lo schema è un errore di convalida. exact Vedi l'indennità Permit2 per un massimo di pagamenti.

La risposta restituisce i seguenti campi in: paymentOutput.cryptoX402

version— La versione del protocollo x402.
payload— La prova della transazione firmata, come oggetto JSON. Allegalo all'X-PAYMENTintestazione e riprova con la richiesta originale.

Un status segno o PROOF_GENERATED indica che la transazione è stata firmata e che la prova di pagamento è inclusa. paymentOutput

Schemi

Un payload x402 nomina a. scheme AgentCore i pagamenti supportano i seguenti schemi:

exact— Paga un importo fisso specificato nel payload del commerciante. Questo è lo schema predefinito e non richiede la gestione delle indennità.
upto— Paga un importo misurato fino a un massimale. Questo schema si risolve tramite il contratto Permit2, quindi il portafoglio del pagatore deve aver concesso un'indennità Permit2. Vedi l'indennità Permit2 per un massimo di pagamenti. Indennità del permesso 2 per un massimo di pagamenti

Indennità del permesso 2 per un massimo di pagamenti

Lo upto schema si risolve tramite il contratto Permit2, che trasferisce i fondi con. transferFrom Il portafoglio del pagatore deve prima concedere a Permit2 un' ERC-20 indennità, altrimenti il regolamento fallisce e si verifica un errore di precondizione. Permit2-allowance Questa concessione segue lo stesso modello di approvazione on-chain di qualsiasi approvazione diretta di Permit2. Per ulteriori informazioni, vedere Uniswap Permit2 sul sito Web Uniswap e le specifiche dello schema x402 upto sul sito Web. https://github.com/coinbase/x402/blob/main/specs/schemes/upto/README.md GitHub

Per gestire questa situazione, impostate la quota massima nella denominazione più piccola dell'asset (permit2AllowanceLimitad esempio, = 1 USDC a 6 decimali). 1000000 Per concedere un'indennità illimitata, passate il uint256 valore massimo come stringa:. 115792089237316195423570985008687907853269984665640564039457584007913129639935 Quando imposti questo campo, AgentCore i pagamenti inviano una approve transazione on-chain prima della firma. Questa transazione comporta commissioni sulla rete blockchain (gas) pagate sul saldo dei token nativi del portafoglio.

Perché approve imposta, anziché aumentare, la quantità consentita dal portafoglio, impostata permit2AllowanceLimit solo quando il portafoglio deve essere approvato (ad esempio, il primo upto pagamento) per evitare una transazione on-chain ridondante. Ometti il campo per saltare completamente la gestione delle quote. Questo campo si applica solo allo upto schema; fornirlo per lo exact schema è un errore di convalida.

L'esempio seguente elabora un upto pagamento e concede un'indennità di 1 USDC a Permit2. Forupto, maxAmountRequired prevede il massimale indicato dal merchant nella sua 402 risposta e funge da facilitatore della transazione in base alla extra.facilitatorAddress stessa risposta.

Esempio

Limitazioni

Il permit2AllowanceLimit campo è valido solo per lo schema. upto Se lo si fornisce per lo exact schema si restituisce unValidationException.

Per gli errori di convalida delle richieste di pagamento x402 e le relative risoluzioni, vedi errori delle richieste di pagamento x402. Per gli errori di elaborazione dei pagamenti e le relative risoluzioni, vedi Errori di elaborazione dei pagamenti. Errori di elaborazione dei pagamenti

Paga una sfida MPP

Quando un commerciante 402 Payment Required risponde a una WWW-Authenticate: Payment sfida, inoltrala alla lettera. paymentInput.mpp AgentCore payments analizza la sfida, controlla il budget, firma con il portafoglio e restituisce un valore di intestazione pronto per l'invio. Authorization AgentCore payments gestisce l'analisi dell'intestazione, la decodifica base64url e la firma, quindi non è necessario eseguire queste operazioni.

Richiesta e risposta

Fornisci i seguenti campi in: paymentInput.mpp

version— La versione del protocollo MPP (ad esempio,1). Obbligatorio.
wwwAuthenticateHeaders— Il valore grezzo dell'WWW-Authenticate: Paymentintestazione della 402 risposta del venditore, passato alla lettera. Fornisci esattamente un'intestazione. Obbligatorio.
buyerPaysGasFees— Se autorizzare il pagamento delle commissioni sulla rete blockchain (gas) dal portafoglio dell'acquirente quando il venditore non le sponsorizza. Opzionale. Omesso o false significa che l'acquirente rifiuta. Vedi Consenso alle commissioni di rete.

La risposta restituisce i seguenti campi inpaymentOutput.mpp:

version— La versione del protocollo MPP.
selectedPaymentId— La id sfida che AgentCore Payments ha pagato, riecheggia nella sfida di input in modo da poter correlare il risultato senza decodificare la credenziale.
paymentCredential— Il valore dell'Authorizationintestazione pronto per l'invio, nel modulo. Payment <base64url-token> Allegalo come Authorization intestazione e riprova con la richiesta originale.

Importante

Non decodificare o modificare. paymentCredential Incorpora la sfida originale e il payload firmato e l'HMAC del commerciante si lega a quei byte esatti. Allega il valore restituito.

L'esempio seguente elabora una sfida MPP. Imposta --payment-type "MPP" e inoltra la WWW-Authenticate: Payment sfida del commerciante alla lettera paymentInput.mpp.wwwAuthenticateHeaders (esattamente un'intestazione).

Esempio

AWS CLI


aws bedrock-agentcore process-payment \
    --payment-manager-arn "arn:aws:bedrock-agentcore:us-west-2:123456789012:payment-manager/my-manager" \
    --payment-session-id "payment-session-abc123" \
    --payment-instrument-id "payment-instrument-xyz789" \
    --payment-type "MPP" \
    --payment-input '{
        "mpp": {
            "version": "1",
            "wwwAuthenticateHeaders": [
                "Payment id=\"c1\", realm=\"seller.example.com\", method=\"evm\", intent=\"charge\", request=\"eyJhbW91bnQiOiIxMDAwMDAifQ\""
            ]
        }
    }' \
    --client-token "$(uuidgen)" \
    --region us-west-2

AWS SDK


import uuid

payment = dp_client.process_payment(
    userId="test-user-123",
    paymentManagerArn=PAYMENT_MANAGER_ARN,
    paymentSessionId=SESSION_ID,
    paymentInstrumentId=INSTRUMENT_ID,
    paymentType="MPP",
    paymentInput={
        "mpp": {
            "version": "1",
            "wwwAuthenticateHeaders": [
                'Payment id="c1", realm="seller.example.com", method="evm", '
                'intent="charge", request="eyJhbW91bnQiOiIxMDAwMDAifQ"'
            ],
        }
    },
    clientToken=str(uuid.uuid4()),
)

Risposta:


{
    "processPaymentId": "12345678-1234-1234-1234-123456789012",
    "paymentManagerArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:payment-manager/my-manager-a1b2c3d4e5",
    "paymentSessionId": "payment-session-abc123def4567",
    "paymentInstrumentId": "payment-instrument-xyz789abc1234",
    "paymentType": "MPP",
    "status": "PROOF_GENERATED",
    "paymentOutput": {
        "mpp": {
            "version": "1",
            "selectedPaymentId": "c1",
            "paymentCredential": "Payment <base64url-token>"
        }
    },
    "createdAt": "2025-07-15T10:35:00Z",
    "updatedAt": "2025-07-15T10:35:02Z"
}

Un status segno o PROOF_GENERATED indica che la credenziale è stata firmata ed è inclusa in. paymentOutput.mpp.paymentCredential

Metodi e token

Una sfida MPP nomina un pagamento. method AgentCore payments supporta i seguenti metodi a tale charge scopo:

evm— Solo USDC canonico. La sfida deve includere e. methodDetails.chainId realm
tempo— Qualsiasi catena Tempo, selezionata damethodDetails.chainId, utilizzando il USDC-equivalent token riconosciuto dalla rete.
solana— The mainnet and devnet networks, solo con tariffe sponsorizzate dal server.

La rete blockchain dello strumento di pagamento deve corrispondere al metodo di sfida. Il supporto del provider dipende dal tipo di connettore:

Metodo	Coinbase CDP	Stripe (Privy)
`evm`	Supportata	Supportato
`tempo`	Supportato	Supportata
`solana`	Non supportata	Supportata

Consenso alla tariffa di rete

Le commissioni relative alla rete blockchain (gas) sono separate dall'importo della sfida. Una sfida pubblicizza chi li sponsorizza attraverso la sua bandiera: methodDetails.feePayer

methodDetails.feePayer=true— Il venditore sponsorizza le commissioni di rete. buyerPaysGasFeesnon ha alcun effetto.
methodDetails.feePayer=falseo assente: l'acquirente paga le commissioni di rete dal portafoglio pagante, oltre all'importo del pagamento. Poiché tale costo non è visibile nell'importo della sfida, AgentCore i pagamenti vengono effettuati solo se impostatibuyerPaysGasFees=true; in caso contrario restituiscono un ValidationException importo. Per quanto riguarda il tempo metodo, questo consenso è richiesto ogni volta che il venditore non sponsorizza le commissioni.

Il evm metodo non richiede il consenso delle commissioni, poiché il facilitatore trasmette la transazione e paga il gas. Oggi il solana metodo supporta solo commissioni sponsorizzate dal server.

Limitazioni

AgentCore i pagamenti soddisfano esattamente una sfida per chiamata. ProcessPayment Fornisci un'unica intestazione. wwwAuthenticateHeaders
Sono supportate solo le modalità charge intent e pull.
Le sfide MPP sono di breve durata. Se la sfida è scaduta, AgentCore Payments restituisce ValidationException e non consuma alcun budget. Richiedi nuovamente la risorsa a pagamento per ottenere una nuova sfida, quindi riprova.

Per gli errori di convalida delle sfide MPP e le relative risoluzioni, vedi Errori di verifica MPP.

Integrazioni con il framework

Per una documentazione di riferimento completa che include la gestione degli errori, le opzioni di configurazione e gli strumenti integrati, vedi Integrazioni con Framework.

Framework	Tipo di integrazione	Documentazione di riferimento
Strands Agents	Plugin (basato su hook)	Gestione delle interruzioni, opzioni di configurazione, strumenti integrati
LangGraph	Middleware (chiude le chiamate agli strumenti)	Richiamate di errore, elenchi consentiti, supporto asincrono, opzioni di configurazione

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

Connessione a Bazaar

Integrazioni con il framework