Payez une demande de paiement x402 Défiez un MPP Intégrations de frameworks

Traiter un paiement

Pour traiter un paiement, vous avez besoin de deux ressources :

Instrument de paiement — Un portefeuille cryptographique intégré avec Coinbase ou Stripe. Consultez la section Création d'un instrument de paiement.
Session de paiement : session limitée dans le temps qui applique éventuellement un budget de dépenses. Consultez la section Créer une session de paiement.

Une fois que les deux existent, appelez ProcessPayment avec l'ID de session de paiement, l'ID de l'instrument de paiement et une charge utile de paiement. Le service valide la demande, vérifie le budget, signe la transaction sur la blockchain appropriée et renvoie un résultat de paiement signé. Pour le schéma complet de la demande et de la réponse, consultez ProcessPayment la référence de l'API.

AgentCore payments prend en charge deux protocoles de paiement, que vous sélectionnez à l'aide du paymentType paramètre :

CRYPTO_X402— Le protocole x402. Entrez la charge utile de paiement x402 du commerçantpaymentInput.cryptoX402, et l'agent réessaie la demande avec la preuve signée dans l'en-tête. X-PAYMENT
MPP— Le protocole de paiement automatique (MPP). Transférez le WWW-Authenticate: Payment défi du marchand et l'agent réessaie la demande avec les informations d'identification renvoyées dans l'Authorizationen-tête. paymentInput.mpp

Choisissez celui paymentType qui correspond au protocole que le marchand a utilisé dans sa 402 Payment Required réponse. Pour les détails de la demande et de la réponse x402, voir Payer une demande de paiement x402. Pour les détails de la demande et de la réponse du MPP, voir Défi Pay an MPP.

Astuce

Vous pouvez automatiser les étapes de cette page à l'aide de la compétence AgentCore Paiements de la boîte à outils de l' AWS agent. La compétence fait partie du plugin aws-agents et permet à un agent de codage IA de créer votre gestionnaire de paiement, votre connecteur, votre fournisseur d'informations d'identification, votre instrument de paiement et votre session à l'aide de la agentcore CLI, et d'ajouter un outil de traitement des paiements à votre agent. Pour plus de détails, consultez le guide de démarrage rapide et la boîte à outils de l'AWS agent sur GitHub.

Il existe cinq manières d'invoquer l' ProcessPayment API :

Exemple

AgentCore CLI

Si votre agent est déployé avec des fonctionnalités de paiement configurées, invoquez-le avec le contexte de paiement et l'intercepteur x402 gère automatiquement le traitement des paiements :


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

Pour utiliser une session explicite au lieu d'en créer une automatiquement, procédez comme suit :


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

Le plug-in x402 de l'agent déployé intercepte les réponses et les appels ProcessPayment HTTP 402 et réessaie la demande avec preuve. Nécessite la AgentCore CLI v0.19.0 ou version ultérieure.

AgentCore SDK

Utilisez cette PaymentManager classe pour générer des en-têtes de paiement manuellement dans n'importe quel framework d'agent :


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_headerscontient l'en-tête de la preuve de paiement. Incluez cet en-tête lorsque vous réessayez d'envoyer la demande au terminal payant. Vous pouvez également appeler la process_payment méthode de PaymentManager pour mieux contrôler les entrées.

AWS CLI

L'exemple suivant traite un paiement x402 en transmettant la charge utile du commerçant : 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

Pour savoir comment créer le paymentInput pour chaque protocole, y compris l'exemple de la AWS CLI MPP, consultez Pay an x402 payment request et Pay an MPP challenge.

AWS SDK

L'exemple suivant traite un paiement x402 en appelant process_payment avec la charge utile du vendeur dans : 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()),
)

Réponse :


{
    "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"
}

Un status de PROOF_GENERATED indique que la transaction a été signée et que la preuve de paiement y est inclusepaymentOutput.

Pour savoir comment créer le paymentInput pour chaque protocole, y compris l'exemple du AWS SDK MPP et sa réponse, consultez Payer une demande de paiement x402 et Pay an MPP challenge.

Strands SDK

Le plugin de AgentCore paiement fournit un traitement automatique des paiements pour Strands Agents. Il prend en charge le protocole x402 Payment Required, permettant aux agents de gérer automatiquement les réponses HTTP 402.

Installation:


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

Configurez et utilisez le 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")

Le plugin de AgentCore paiement intercepte automatiquement les demandes de paiement x402, traite le paiement et réessaie la demande avec une preuve de paiement pour l'agent.

LangGraph

L'intergiciel de AgentCore paiement permet le traitement automatique des paiements pour les LangGraph agents. Il prend en charge le protocole x402 Payment Required, permettant aux agents de gérer automatiquement les réponses HTTP 402.

Installation:


pip install 'bedrock-agentcore[langgraph]'

Configurez et utilisez le 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)

L'intergiciel de AgentCore paiement intercepte automatiquement les demandes de paiement x402, traite le paiement et réessaie la demande avec une preuve de paiement pour l'agent.

Payez une demande de paiement x402

Lorsqu'un commerçant répond en indiquant une charge utile de paiement x402 dans sa 402 Payment Required réponse, vous transférez cette charge à AgentCore Payments, et AgentCore Payments renvoie une preuve signée. Vous copiez la charge utile du commerçant danspaymentInput.cryptoX402, and AgentCore payments vérifie le budget, signe la transaction avec le portefeuille et renvoie la preuve signée. Vous joignez la preuve à l'X-PAYMENTen-tête et réessayez la demande initiale.

Demande et réponse

Renseignez les champs suivants dans paymentInput.cryptoX402 :

version— La version du protocole x402 (par exemple, 1 ou2). Obligatoire.
payload— Les exigences de paiement x402 du marchand, transmises sous forme d'objet JSON. Cela spécifie les champs schemenetwork,maxAmountRequired,asset,payTo, et les autres champs de la 402 réponse du vendeur. Obligatoire.
permit2AllowanceLimit— L'allocation maximale de Permit2 en chaîne à accorder, dans la plus petite dénomination de l'actif. Facultatif. Définissez cette option uniquement pour le schéma upto (mesuré), qui est réglé par le biais du contrat Permit2 ; le fournir pour le exact schéma constitue une erreur de validation. Voir l'allocation Permit 2 pour les paiements jusqu'à concurrence.

La réponse renvoie les champs suivants dans paymentOutput.cryptoX402 :

version— La version du protocole x402.
payload— La preuve de transaction signée, sous forme d'objet JSON. Joignez-le à l'X-PAYMENTen-tête et réessayez la demande initiale.

Un status of PROOF_GENERATED indique que la transaction a été signée et que la preuve de paiement y est inclusepaymentOutput.

Schémas

Une charge utile x402 nomme un. scheme AgentCore payments prend en charge les programmes suivants :

exact— Paie un montant fixe spécifié dans la charge utile du commerçant. Il s'agit du schéma par défaut, qui ne nécessite aucune gestion des allocations.
upto— Paie un montant mesuré jusqu'à un plafond. Ce système est réglé par le biais du contrat Permit2, de sorte que le portefeuille du payeur doit avoir accordé une allocation Permit2. Voir l'allocation Permit 2 pour les paiements jusqu'à concurrence.

Allocation Permit 2 pouvant aller jusqu'à concurrence

Le upto programme est réglé par le biais du contrat Permit2, qui transfère des fonds avec. transferFrom Le portefeuille du payeur doit d'abord accorder une ERC-20 allocation à Permit2, sinon le règlement échoue en raison d'une erreur de condition Permit2-allowance préalable. Cette subvention suit le même modèle d'approbation en chaîne que toute approbation directe de Permit2. Pour plus d'informations, consultez Uniswap Permit2 sur le site Web d'Uniswap et la spécification du schéma x402 upto sur le site Web. GitHub

Pour gérer cela, définissez permit2AllowanceLimit l'allocation maximale dans la plus petite dénomination de l'actif (par exemple, 1000000 = 1 USDC à 6 décimales). Pour accorder une allocation illimitée, transmettez la uint256 valeur maximale sous forme de chaîne :115792089237316195423570985008687907853269984665640564039457584007913129639935. Lorsque vous définissez ce champ, AgentCore Payments soumet une approve transaction en chaîne avant de signer. Cette transaction entraîne des frais de réseau blockchain (gaz) payés à partir du solde des jetons natifs du portefeuille.

Parce que approve définit, au lieu d'augmenter, l'allocation du portefeuille, définie permit2AllowanceLimit uniquement lorsque le portefeuille doit être approuvé (par exemple, lors de son premier upto paiement) afin d'éviter une transaction en chaîne redondante. Omettez ce champ pour ignorer complètement la gestion des allocations. Ce champ s'applique uniquement au upto schéma ; le fournir pour le exact schéma constitue une erreur de validation.

L'exemple suivant traite un upto paiement et accorde une allocation de 1 USDC à Permit2. Carupto, maxAmountRequired fixe le plafond annoncé par le commerçant dans sa 402 réponse et facilite extra.facilitatorAddress le règlement à partir de cette même réponse.

Exemple

Limitations

Le permit2AllowanceLimit champ n'est valide que pour le upto schéma. Le fournir pour le exact schéma renvoie unValidationException.

Pour les erreurs de validation des demandes de paiement x402 et leurs résolutions, voir Erreurs de demande de paiement x402. Pour les erreurs de traitement des paiements et leur résolution, voir Erreurs de traitement des paiements.

Défiez un MPP

Lorsqu'un marchand renvoie un WWW-Authenticate: Payment défi dans sa 402 Payment Required réponse, transférez le défi mot pour mot. paymentInput.mpp AgentCore payments analyse le défi, vérifie le budget, signe avec le portefeuille et renvoie une valeur d'Authorizationen-tête prête à être envoyée. AgentCore payments gère l'analyse des en-têtes, le décodage base64url et la signature. Vous n'avez donc pas besoin d'effectuer ces opérations.

Demande et réponse

Renseignez les champs suivants dans paymentInput.mpp :

version— La version du protocole MPP (par exemple,1). Obligatoire.
wwwAuthenticateHeaders— La valeur WWW-Authenticate: Payment d'en-tête brute de la 402 réponse du vendeur, transmise mot pour mot. Fournissez exactement un en-tête. Obligatoire.
buyerPaysGasFees— S'il faut autoriser le paiement des frais du réseau blockchain (gaz) depuis le portefeuille de l'acheteur lorsque le vendeur ne le sponsorise pas. Facultatif. Omis ou false signifie que l'acheteur refuse. Voir Consentement aux frais de réseau.

La réponse renvoie les champs suivants dans paymentOutput.mpp :

version— Version du protocole MPP.
selectedPaymentId— Le id défi que AgentCore Payments a payé, repris du défi de saisie afin que vous puissiez corréler le résultat sans décoder l'identifiant.
paymentCredential— La valeur d'Authorizationen-tête prête à être envoyée, dans le formulairePayment <base64url-token>. Joignez-le en tant qu'Authorizationen-tête et réessayez la demande d'origine.

Important

Ne décodez pas et ne modifiez paymentCredential pas. Il intègre le défi d'origine et la charge utile signée, et le HMAC du marchand se lie à ces octets exacts. Joignez la valeur telle qu'elle a été renvoyée.

L'exemple suivant traite un défi MPP. Définissez --payment-type "MPP" et transmettez le WWW-Authenticate: Payment défi du marchand mot pour mot paymentInput.mpp.wwwAuthenticateHeaders (exactement un en-tête).

Exemple

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()),
)

Réponse :


{
    "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 de PROOF_GENERATED indique que le justificatif a été signé et qu'il est inclus danspaymentOutput.mpp.paymentCredential.

Méthodes et jetons

Un défi MPP désigne un paiementmethod. AgentCore payments prend en charge les méthodes suivantes à cette charge fin :

evm— USDC canonique uniquement. Le défi doit inclure methodDetails.chainId etrealm.
tempo— Toute chaîne Tempo, sélectionnée parmethodDetails.chainId, à l'aide du USDC-equivalent jeton reconnu du réseau.
solana— Les devnet réseaux mainnet et, avec des frais sponsorisés par le serveur uniquement.

Le réseau blockchain de l'instrument de paiement doit correspondre à la méthode de challenge. L'assistance du fournisseur dépend du type de connecteur :

Méthode	Coinbase CDP	Stripe (Privy)
`evm`	Pris en charge	Pris en charge
`tempo`	Pris en charge	Pris en charge
`solana`	Non pris en charge	Pris en charge

Consentement aux frais de réseau

Les frais du réseau blockchain (gaz) sont distincts du montant du défi. Un challenge annonce qui les sponsorise par le biais de son methodDetails.feePayer drapeau :

methodDetails.feePayer=true— Le vendeur sponsorise les frais de réseau. buyerPaysGasFeesn'a aucun effet.
methodDetails.feePayer=falseou absent — L'acheteur paie les frais de réseau depuis le portefeuille payant, en plus du montant du paiement. Comme ce coût n'est pas visible dans le montant du défi, AgentCore les paiements ne sont signés que si vous le définissez buyerPaysGasFees=true ; sinon, il renvoie unValidationException. Pour la tempo méthode, ce consentement est requis chaque fois que le vendeur ne sponsorise pas les frais.

La evm méthode ne nécessite aucun consentement, car l'animateur diffuse la transaction et paie l'essence. La solana méthode ne prend en charge que les frais sponsorisés par le serveur aujourd'hui.

Limitations

AgentCore payments répond exactement à un défi par ProcessPayment appel. Fournissez un en-tête unique danswwwAuthenticateHeaders.
Seuls les modes charge intention et pull sont pris en charge.
Les défis du MPP sont de courte durée. Si le challenge a expiré, AgentCore les paiements renvoient un A ValidationException et ne consomment aucun budget. Demandez à nouveau la ressource payante pour obtenir un nouveau défi, puis réessayez.

Pour les erreurs de validation des défis MPP et leurs résolutions, voir Erreurs de défi MPP.

Intégrations de frameworks

Pour une documentation de référence complète, y compris la gestion des erreurs, les options de configuration et les outils intégrés, consultez la section Intégrations de Framework.

Cadre	Type d’intégration	Référence
Strands & Agents	Plugin (basé sur des crochets)	Gestion des interruptions, options de configuration, outils intégrés
LangGraph	Middleware (enveloppe les appels d'outils)	Rappels d'erreur, listes d'autorisations, support asynchrone, options de configuration

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Connexion à Bazaar

Intégrations de frameworks