Pague uma solicitação de pagamento x402 Pague um desafio de MPP Integrações do framework

Processar um pagamento

Para processar um pagamento, você precisa de dois recursos:

Instrumento de pagamento — Uma carteira criptográfica incorporada com Coinbase ou Stripe. Consulte Criar um instrumento de pagamento.
Sessão de pagamento — Uma sessão com limite de tempo que, opcionalmente, impõe um orçamento de gastos. Consulte Criar uma sessão de pagamento.

Depois que ambos existirem, ligue ProcessPayment com o ID da sessão de pagamento, o ID do instrumento de pagamento e uma carga de pagamento. O serviço valida a solicitação, verifica o orçamento, assina a transação no blockchain apropriado e retorna um resultado de pagamento assinado. Para ver o esquema completo de solicitação e resposta, consulte ProcessPayment a Referência da API.

AgentCore pagamentos suportam dois protocolos de pagamento, que você seleciona com o paymentType parâmetro:

CRYPTO_X402— O protocolo x402. Forneça a carga de pagamento x402 do lojista e o agente repetirá a solicitação com o comprovante assinado no cabeçalho. paymentInput.cryptoX402 X-PAYMENT
MPP— O Protocolo de Pagamentos por Máquina (MPP). Encaminhe o WWW-Authenticate: Payment desafio do lojista e o agente repetirá a solicitação com a credencial devolvida no cabeçalho. paymentInput.mpp Authorization

Escolha o paymentType que corresponda ao protocolo que o lojista usou em sua 402 Payment Required resposta. Para obter detalhes sobre solicitações e respostas x402, consulte Pagar uma solicitação de pagamento x402. Para obter detalhes sobre solicitações e respostas de MPP, consulte Pagar um desafio de MPP.

dica

Você pode automatizar as etapas nesta página com a habilidade AgentCore Pagamentos no kit de ferramentas do AWS agente. A habilidade faz parte do plug-in aws-agents e permite que um agente de codificação de IA crie seu gerenciador de pagamentos, conector, provedor de credenciais, instrumento de pagamento e sessão usando a agentcore CLI e adicione uma ferramenta de pagamento por processo ao seu agente. Para obter detalhes, consulte o guia de início rápido e o kit de ferramentas do AWS agente em. GitHub

Há cinco maneiras de invocar a ProcessPayment API:

exemplo

AgentCore CLI

Se seu agente estiver implantado com recursos de pagamento configurados, invoque-o com o contexto de pagamento e o interceptor x402 gerenciará o processamento do pagamento automaticamente:


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

Para usar uma sessão explícita em vez de criar uma automaticamente:


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

O plug-in x402 do agente implantado intercepta respostas e chamadas HTTP 402 e repete a ProcessPayment solicitação com prova. Requer AgentCore CLI v0.19.0 ou posterior.

AgentCore SDK

Use a PaymentManager classe para gerar cabeçalhos de pagamento manualmente em qualquer estrutura de agente:


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_headerscontém o cabeçalho do comprovante de pagamento. Inclua esse cabeçalho ao tentar novamente a solicitação para o endpoint pago. Você também pode chamar o process_payment método de PaymentManager para obter mais controle sobre as entradas.

AWS CLI

O exemplo a seguir processa um pagamento x402 transmitindo a carga útil do lojista: 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

Para saber como criar o paymentInput para cada protocolo, incluindo o exemplo da AWS CLI do MPP, consulte Pagar uma solicitação de pagamento x402 e Pagar um desafio MPP.

AWS SDK

O exemplo a seguir processa um pagamento x402 ligando process_payment com a carga útil do lojista em: 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()),
)

Resposta:


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

Um status PROOF_GENERATED sinal indica que a transação foi assinada e o comprovante de pagamento está incluídopaymentOutput.

Para saber como criar o paymentInput para cada protocolo, incluindo o exemplo do AWS SDK do MPP e sua resposta, consulte Pagar uma solicitação de pagamento x402 e Pagar um desafio MPP.

Strands SDK

O plugin de AgentCore pagamentos fornece processamento automatizado de pagamentos para agentes Strands. Ele suporta o protocolo x402 Payment Required, permitindo que os agentes processem automaticamente as respostas HTTP 402.

Instalação:


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

Configure e use o 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")

O plug-in de AgentCore pagamentos intercepta solicitações de pagamento x402 automaticamente, processa o pagamento e repete a solicitação com o comprovante de pagamento do agente.

LangGraph

O middleware de AgentCore pagamentos fornece processamento automatizado de pagamentos para LangGraph agentes. Ele suporta o protocolo x402 Payment Required, permitindo que os agentes processem automaticamente as respostas HTTP 402.

Instalação:


pip install 'bedrock-agentcore[langgraph]'

Configure e use o 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)

O middleware de AgentCore pagamentos intercepta automaticamente as solicitações de pagamento x402, processa o pagamento e repete a solicitação com o comprovante de pagamento do agente.

Pague uma solicitação de pagamento x402

Quando um lojista responde com uma carga de pagamento x402 em sua 402 Payment Required resposta, você encaminha essa carga para pagamentos e AgentCore os AgentCore pagamentos devolvem um comprovante assinado. Você copia a carga útil do comerciante e AgentCore os pagamentos verificam o orçamento, assinam a transação com a carteira e devolvem o comprovante assinado. paymentInput.cryptoX402 Você anexa a prova ao X-PAYMENT cabeçalho e repete a solicitação original.

Solicitação e reposta

Forneça os seguintes campos empaymentInput.cryptoX402:

version— A versão do protocolo x402 (por exemplo, 1 ou2). Obrigatório.
payload— Os requisitos de pagamento x402 do lojista, passados como um objeto JSON. Isso especifica oscheme,network,maxAmountRequired, assetpayTo, e outros campos da resposta do lojista. 402 Obrigatório.
permit2AllowanceLimit— O subsídio máximo de Permit2 em cadeia a ser concedido, na menor denominação do ativo. Opcional. Defina isso somente para o esquema upto (medido), que é liquidado por meio do contrato Permit2; fornecê-lo para o exact esquema é um erro de validação. Consulte o subsídio Permission 2 para até pagamentos.

A resposta retorna os seguintes campos empaymentOutput.cryptoX402:

version— A versão do protocolo x402.
payload— A prova de transação assinada, como um objeto JSON. Anexe-o ao X-PAYMENT cabeçalho e repita a solicitação original.

Um status de PROOF_GENERATED indica que a transação foi assinada e o comprovante de pagamento está incluídopaymentOutput.

Esquemas

Uma carga útil x402 nomeia a. scheme AgentCore os pagamentos suportam os seguintes esquemas:

exact— Paga um valor fixo especificado na carga útil do lojista. Esse é o esquema padrão e não requer tratamento de subsídios.
upto— Paga uma quantia medida até um teto. Esse esquema é estabelecido por meio do contrato Permit2, portanto, a carteira do pagador deve ter concedido um subsídio Permit2. Consulte o subsídio Permission 2 para até pagamentos.

Subsídio Permission 2 para até pagamentos

O upto esquema é liquidado por meio do contrato Permit2, que movimenta fundos com. transferFrom A carteira do pagador deve primeiro conceder uma ERC-20 mesada à Permit2, ou a liquidação falhará com um Permit2-allowance erro de pré-condição. Essa concessão segue o mesmo modelo de aprovação em cadeia de qualquer aprovação direta da Permit2. Para obter mais informações, consulte Uniswap Permit2 no site da Uniswap e a especificação do esquema x402 upto no site. GitHub

Para lidar com isso, permit2AllowanceLimit defina a margem máxima na menor denominação do ativo (por exemplo, 1000000 = 1 USDC com 6 casas decimais). Para conceder um subsídio ilimitado, passe o uint256 valor máximo como uma string:115792089237316195423570985008687907853269984665640564039457584007913129639935. Quando você define esse campo, o AgentCore Payments envia uma approve transação em cadeia antes de assinar. Essa transação incorre em taxas de rede blockchain (gás) pagas a partir do saldo do token nativo da carteira.

Porque approve define, em vez de aumentar, a franquia da carteira, definida permit2AllowanceLimit somente quando a carteira precisa ser aprovada (por exemplo, seu primeiro upto pagamento) para evitar uma transação redundante na cadeia. Omita o campo para ignorar totalmente o tratamento da mesada. Esse campo se aplica somente ao upto esquema; fornecê-lo para o exact esquema é um erro de validação.

O exemplo a seguir processa um upto pagamento e concede uma mesada de 1 USDC à Permit2. Poisupto, maxAmountRequired carrega o teto que o comerciante anuncia em sua 402 resposta e extra.facilitatorAddress é o facilitador da liquidação dessa mesma resposta.

exemplo

Limitações

O permit2AllowanceLimit campo é válido somente para o upto esquema. Fornecê-lo para o exact esquema retorna umValidationException.

Para erros de validação de solicitação de pagamento x402 e suas resoluções, consulte Erros de solicitação de pagamento x402. Para erros de processamento de pagamentos e suas soluções, consulte Erros Erros no processamento de pagamentos de processamento de pagamentos.

Pague um desafio de MPP

Quando um lojista devolver um WWW-Authenticate: Payment desafio em sua 402 Payment Required resposta, encaminhe o desafio na íntegra. paymentInput.mpp AgentCore payments analisa o desafio, verifica o orçamento, assina com a carteira e retorna um valor de cabeçalho pronto para envioAuthorization. AgentCore payments manipula a análise do cabeçalho, a decodificação base64url e a assinatura, portanto, você não precisa realizar essas operações.

Solicitação e reposta

Forneça os seguintes campos empaymentInput.mpp:

version— A versão do protocolo MPP (por exemplo,1). Obrigatório.
wwwAuthenticateHeaders— O valor bruto do WWW-Authenticate: Payment cabeçalho da 402 resposta do lojista, passado literalmente. Forneça exatamente um cabeçalho. Obrigatório.
buyerPaysGasFees— Se deve autorizar o pagamento de taxas de rede blockchain (gás) da carteira do comprador quando o vendedor não as patrocina. Opcional. Omitido ou false significa que o comprador recusa. Consulte Consentimento de taxa de rede.

A resposta retorna os seguintes campos empaymentOutput.mpp:

version— A versão do protocolo MPP.
selectedPaymentId— O desafio id de que os AgentCore pagamentos pagaram surgiu do desafio de entrada, para que você possa correlacionar o resultado sem decodificar a credencial.
paymentCredential— O valor do Authorization cabeçalho pronto para envio, no formulário. Payment <base64url-token> Anexe-o como Authorization cabeçalho e repita a solicitação original.

Importante

Não decodifique nem modifiquepaymentCredential. Ele incorpora o desafio original e a carga assinada, e o HMAC do comerciante se vincula a esses bytes exatos. Anexe o valor conforme retornado.

O exemplo a seguir processa um desafio de MPP. Defina --payment-type "MPP" e encaminhe o WWW-Authenticate: Payment desafio do lojista literalmente em paymentInput.mpp.wwwAuthenticateHeaders (exatamente um cabeçalho).

exemplo

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

Resposta:


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

Um status de PROOF_GENERATED indica que a credencial foi assinada e está incluída empaymentOutput.mpp.paymentCredential.

Métodos e tokens

Um desafio de MPP nomeia um pagamentomethod. AgentCore os pagamentos suportam os seguintes métodos para a charge intenção:

evm— Somente USDC canônico. O desafio deve incluir methodDetails.chainId realm e.
tempo— Qualquer cadeia de Tempo, selecionada pormethodDetails.chainId, usando o USDC-equivalent token reconhecido da rede.
solana— As devnet redes mainnet e, somente com taxas patrocinadas pelo servidor.

A rede blockchain do instrumento de pagamento deve corresponder ao método de desafio. O suporte do provedor depende do tipo de conector:

Método	CDP da Coinbase	Stripe (Privado)
`evm`	Compatível	Compatível
`tempo`	Compatível	Compatível
`solana`	Não compatível	Compatível

Consentimento de taxa de rede

As taxas da rede Blockchain (gás) são separadas do valor do desafio. Um desafio anuncia quem os patrocina por meio de sua methodDetails.feePayer bandeira:

methodDetails.feePayer=true— O vendedor patrocina as taxas da rede. buyerPaysGasFeesnão tem efeito.
methodDetails.feePayer=falseou ausente — O comprador paga as taxas de rede da carteira pagadora, além do valor do pagamento. Como esse custo não está visível no valor do desafio, os AgentCore pagamentos são assinados somente se você definirbuyerPaysGasFees=true; caso contrário, ele retornará umValidationException. Para o tempo método, esse consentimento é necessário sempre que o vendedor não patrocina taxas.

O evm método não precisa de consentimento de taxa, porque o facilitador transmite a transação e paga o gás. Atualmente, o solana método suporta apenas taxas patrocinadas pelo servidor.

Limitações

AgentCore os pagamentos cumprem exatamente um desafio por ProcessPayment chamada. Forneça um único cabeçalho emwwwAuthenticateHeaders.
Somente os modos charge intent e pull são suportados.
Os desafios do MPP duram pouco. Se o desafio expirar, AgentCore os pagamentos retornam ValidationException e não consomem nenhum orçamento. Solicite o recurso pago novamente para obter um novo desafio e tente novamente.

Para erros de validação de desafio de MPP e suas resoluções, consulte Erros de desafio de MPP.

Integrações do framework

Para obter a documentação de referência completa, incluindo tratamento de erros, opções de configuração e ferramentas integradas, consulte Integrações do Framework.

Framework	Tipo de integração	Referência
Agentes Strands	Plugin (baseado em gancho)	Tratamento de interrupções, opções de configuração, ferramentas integradas
LangGraph	Middleware (envolve chamadas de ferramentas)	Retornos de chamada de erro, listas de permissões, suporte assíncrono, opções de configuração

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Conectando-se ao Bazaar

Integrações do framework