x402 支払いリクエストの支払い MPP チャレンジの支払いフレームワークの統合

支払いの処理

支払いを処理するには、次の 2 つのリソースが必要です。

支払い手段 — Coinbase または Stripe を備えた埋め込み暗号ウォレット。「支払い手段の作成」を参照してください。
支払いセッション — オプションで支出予算を適用する時間制限付きセッション。「支払いセッションを作成する」を参照してください。

両方が存在したら、支払いセッション ID、支払い手段 ID、および支払いペイロードProcessPaymentを使用してを呼び出します。サービスはリクエストを検証し、予算を確認し、適切なブロックチェーンでトランザクションに署名して、署名された支払い結果を返します。完全なリクエストとレスポンスのスキーマについては、 API リファレンスのProcessPayment」を参照してください。

AgentCore 支払いは、 paymentTypeパラメータで選択する 2 つの支払いプロトコルをサポートしています。

CRYPTO_X402 — x402 プロトコル。でマーチャントの x402 支払いペイロードを指定するとpaymentInput.cryptoX402、エージェントは X-PAYMENTヘッダーの署名付き証明を使用してリクエストを再試行します。
MPP — Machine Payments Protocol (MPP)。でマーチャントのWWW-Authenticate: Paymentチャレンジを転送するとpaymentInput.mpp、エージェントは Authorizationヘッダーに返された認証情報を使用してリクエストを再試行します。

マーチャントが402 Payment Requiredレスポンスに使用したプロトコルに一致する paymentTypeを選択します。x402 リクエストとレスポンスの詳細については、「x402 支払いリクエストの支払い」を参照してください。MPP リクエストとレスポンスの詳細については、「MPP チャレンジの支払い」を参照してください。

ヒント

エージェント AWS ツールキットの AgentCore Payments スキルを使用して、このページのステップを自動化できます。このスキルは aws-agents プラグインの一部であり、AI コーディングエージェントが agentcore CLI を使用して Payment Manager、コネクタ、認証情報プロバイダー、支払い手段、セッションを作成し、エージェントにプロセス支払いツールを追加できるようにします。詳細については、GitHub のクイックスタートとエージェントツールキットを参照してください。 AWS GitHub

ProcessPayment API を呼び出すには、次の 5 つの方法があります。

例

AgentCore CLI

エージェントが支払い機能を設定した状態でデプロイされている場合は、支払いコンテキストを使用してエージェントを呼び出し、x402 インターセプターが支払い処理を自動的に処理します。


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

自動作成の代わりに明示的なセッションを使用するには:


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

デプロイされたエージェントの x402 プラグインは、HTTP 402 レスポンスをインターセプトし、を呼び出しProcessPayment、証明付きでリクエストを再試行します。AgentCore CLI v0.19.0 以降が必要です。

AgentCore SDK

PaymentManager クラスを使用して、エージェントフレームワーク内で支払いヘッダーを手動で生成します。


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_headers には、支払い証明ヘッダーが含まれています。有料エンドポイントへのリクエストを再試行する場合は、このヘッダーを含めます。の process_paymentメソッドを呼び出しPaymentManagerて、入力をより詳細に制御することもできます。

AWS CLI

次の例では、でマーチャントのペイロードを渡すことで x402 支払いを処理します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

MPP AWS CLI の例など、プロトコルpaymentInputごとにを構築する方法については、「x402 支払いリクエストの支払い」および「MPP チャレンジの支払い」を参照してください。

AWS SDK

次の例では、でマーチャントのペイロードprocess_paymentを使用してを呼び出して x402 支払いを処理します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()),
)

レスポンス:


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

status のは、トランザクションが署名され、支払い証明がに含まれているPROOF_GENERATEDことを示しますpaymentOutput。

MPP AWS SDK の例とそのレスポンスなど、プロトコルpaymentInputごとにを構築する方法については、「x402 支払いリクエストの支払い」と「MPP チャレンジの支払い」を参照してください。

Strands SDK

AgentCore 支払いプラグインは、Strands エージェントの自動支払い処理を提供します。x402 Payment Required プロトコルをサポートしているため、エージェントは HTTP 402 レスポンスを自動的に処理できます。

インストール:


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

プラグインを設定して使用します。


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")

AgentCore 支払いプラグインは、x402 支払いリクエストを自動的にインターセプトし、支払いを処理し、エージェントの支払い証明を使用してリクエストを再試行します。

LangGraph

AgentCore 支払いミドルウェアは、LangGraph エージェントの自動支払い処理を提供します。x402 Payment Required プロトコルをサポートしているため、エージェントは HTTP 402 レスポンスを自動的に処理できます。

インストール:


pip install 'bedrock-agentcore[langgraph]'

ミドルウェアを設定して使用します。


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)

AgentCore 支払いミドルウェアは、x402 支払いリクエストを自動的にインターセプトし、支払いを処理し、エージェントの支払い証明を使用してリクエストを再試行します。

x402 支払いリクエストの支払い

マーチャントが応答で x402 支払いペイロードで402 Payment Required応答すると、そのペイロードを AgentCore 支払いに転送し、AgentCore 支払いは署名付き証明を返します。マーチャントのペイロードをにコピーするとpaymentInput.cryptoX402、AgentCore 支払いは予算を確認し、ウォレットでトランザクションに署名して、署名された証明を返します。証明をX-PAYMENTヘッダーにアタッチし、元のリクエストを再試行します。

リクエストとレスポンス

で次のフィールドを指定しますpaymentInput.cryptoX402。

version — x402 プロトコルバージョン (例: 1または 2)。必須。
payload — JSON オブジェクトとして渡される、マーチャントの x402 支払い要件。これはscheme、マーチャントの402レスポンスの network、maxAmountRequired、payTo、、asset、およびその他のフィールドを指定します。必須。
permit2AllowanceLimit — アセットの最小額面金額で付与するチェーン上の Permit2 の最大許容量。オプション。これは、Permit2 契約を通じて決済される upto (従量制) スキームに対してのみ設定します。exactスキームに指定することは検証エラーです。「最大支払いの Permit2 許容量」を参照してください。

レスポンスは、で次のフィールドを返しますpaymentOutput.cryptoX402。

version — x402 プロトコルバージョン。
payload — JSON オブジェクトとして署名されたトランザクション証明。X-PAYMENT ヘッダーにアタッチし、元のリクエストを再試行します。

status の PROOF_GENERATEDは、トランザクションが署名され、支払い証明がに含まれていることを示しますpaymentOutput。

スキーム

x402 ペイロードはに名前を付けますscheme。AgentCore 支払いでは、次のスキームがサポートされています。

exact — マーチャントのペイロードで指定された固定額を支払います。これはデフォルトのスキームであり、手当の処理は必要ありません。
upto — 上限まで計測された金額を支払います。このスキームは Permit2 契約を通じて決済されるため、支払者ウォレットは Permit2 手当を付与している必要があります。「最大支払いの Permit2 許容量」を参照してください。

最大支払いの Permit2 許容量

upto スキームは、で資金を移動する Permit2 契約を通じて決済されますtransferFrom。支払者ウォレットは、まず Permit2 に ERC-20 許容量を付与する必要があります。そうしないと、決済が Permit2-allowanceの前提条件エラーで失敗します。この許可は、直接の Permit2 承認と同じオンチェーン承認モデルに従います。詳細については、Uniswap ウェブサイトの「Uniswap Permit2」および GitHub ウェブサイトの「x402 upto scheme specification」を参照してください。

これを処理するには、 permit2AllowanceLimitをアセットの最小単位の最大許容量に設定します (例えば、小数 6 桁で 1000000 = 1 USDC)。無制限の許容量を付与するには、uint256最大値を文字列として渡します115792089237316195423570985008687907853269984665640564039457584007913129639935。このフィールドを設定すると、AgentCore 支払いは署名前にオンチェーンapproveトランザクションを送信します。このトランザクションでは、ウォレットのネイティブトークン残高から支払われたブロックチェーンネットワーク (ガス) 料金が発生します。

approve はウォレットの許容量を追加するのではなく、を設定するため、冗長なオンチェーントランザクションを回避するためにウォレットの承認 (最初のupto支払いなど) が必要なpermit2AllowanceLimit場合にのみを設定します。許容範囲の処理を完全にスキップするには、フィールドを省略します。このフィールドはuptoスキームにのみ適用されます。exactスキームに指定することは検証エラーです。

次の例では、upto支払いを処理し、1 USDC の許容額を Permit2 に付与します。の場合upto、 maxAmountRequiredはマーチャントが402レスポンスでアドバタイズする上限を保持し、同じレスポンスの決済ファシリテーターextra.facilitatorAddressです。

例

制限事項

permit2AllowanceLimit フィールドはuptoスキームに対してのみ有効です。exact スキームにこれを指定すると、が返されますValidationException。

x402 支払いリクエストの検証エラーとその解決策については、「x402 支払いリクエストエラー」を参照してください。支払い処理エラーとその解決策については、「支払い処理エラー」を参照してください。

MPP チャレンジの支払い

マーチャントが402 Payment RequiredレスポンスでWWW-Authenticate: Paymentチャレンジを返す場合は、でチャレンジを逐語的に転送しますpaymentInput.mpp。AgentCore 支払いは、チャレンジを解析し、予算を確認し、ウォレットに署名して、ready-to-sendAuthorizationヘッダー値を返します。AgentCore 支払いはヘッダー解析、base64url デコード、署名を処理するため、これらのオペレーションを実行する必要はありません。

リクエストとレスポンス

で次のフィールドを指定しますpaymentInput.mpp。

version — MPP プロトコルバージョン (例: 1)。必須。
wwwAuthenticateHeaders — マーチャントの402レスポンスからの raw WWW-Authenticate: Paymentヘッダー値。逐語的に渡されます。ヘッダーを 1 つだけ指定します。必須。
buyerPaysGasFees — 販売者がそれらをスポンサーしない場合に、購入者のウォレットからのブロックチェーンネットワーク (ガス) 料金の支払いを許可するかどうか。オプション。省略またはは、購入者が辞退するfalseことを意味します。「ネットワーク料金の同意」を参照してください。

レスポンスは、で次のフィールドを返しますpaymentOutput.mpp。

version — MPP プロトコルバージョン。
selectedPaymentId — AgentCore の支払いが支払ったチャレンジidのは、認証情報をデコードせずに結果を関連付けられるように、入力チャレンジからエコーしました。
paymentCredential — ready-to-sendAuthorizationヘッダー値。の形式ですPayment <base64url-token>。Authorization ヘッダーとしてアタッチし、元のリクエストを再試行します。

重要

をデコードまたは変更しないでくださいpaymentCredential。元のチャレンジと署名付きペイロードが埋め込まれ、マーチャントの HMAC はそれらの正確なバイトにバインドされます。返された値を添付します。

次のの例では、MPP チャレンジを処理します。でマーチャントのWWW-Authenticate: Paymentチャレンジを逐語的に設定--payment-type "MPP"して転送します paymentInput.mpp.wwwAuthenticateHeaders (1 つのヘッダーのみ）。

例

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

レスポンス:


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

status のは、認証情報が署名され、に含まれているPROOF_GENERATEDことを示しますpaymentOutput.mpp.paymentCredential。

メソッドとトークン

MPP チャレンジは支払いにという名前を付けますmethod。AgentCore 支払いは、インchargeテントに対して次の方法をサポートしています。

evm — 正規 USDC のみ。チャレンジには methodDetails.chainIdとを含める必要がありますrealm。
tempo — ネットワークで認識された USDC に相当するトークンを使用してmethodDetails.chainId、によって選択されたテンポチェーン。
solana — mainnetおよび devnetネットワーク。サーバースポンサー料金のみ。

支払い手段のブロックチェーンネットワークは、チャレンジ方法と一致する必要があります。プロバイダーのサポートはコネクタタイプによって異なります。

方法	コインベース CDP	ストライプ (プライベート)
`evm`	サポート対象	サポート対象
`tempo`	サポート対象	サポート
`solana`	サポート外	サポート

ネットワーク料金の同意

ブロックチェーンネットワーク (ガス) 料金は、チャレンジ量とは異なります。チャレンジは、そのmethodDetails.feePayerフラグを使用してスポンサーをアドバタイズします。

methodDetails.feePayer=true — 販売者はネットワーク料金をスポンサーします。 buyerPaysGasFeesは効果がありません。
methodDetails.feePayer=false または不在 — 購入者は、支払い金額に加えて、支払いウォレットからネットワーク料金を支払います。そのコストはチャレンジ額に表示されないため、AgentCore 支払いはを設定した場合にのみ署名しますbuyerPaysGasFees=true。それ以外の場合はを返しますValidationException。このtempo方法では、販売者が料金をスポンサーしないときは常にこの同意が必要です。

進行役がトランザクションをブロードキャストし、ガスを支払うため、evmこの方法には料金の同意は必要ありません。solana メソッドは現在、サーバースポンサー料金のみをサポートしています。

制限事項

AgentCore の支払いは、ProcessPayment呼び出しごとに 1 つのチャレンジのみを実行します。で 1 つのヘッダーを指定しますwwwAuthenticateHeaders。
charge インテントモードとプルモードのみがサポートされています。
MPP チャレンジは短期間です。チャレンジの有効期限が切れている場合、AgentCore 支払いはを返しValidationException、予算を消費しません。有料リソースを再度リクエストして新しいチャレンジを取得し、再試行します。

MPP チャレンジ検証エラーとその解決策については、「MPP チャレンジエラー」を参照してください。

フレームワークの統合

エラー処理、設定オプション、組み込みツールを含む完全なリファレンスドキュメントについては、「フレームワークの統合」を参照してください。

フレームワーク	統合タイプ	リファレンス
ストランドエージェント	プラグイン (フックベース)	割り込み処理、設定オプション、組み込みツール
LangGraph	ミドルウェア (ツール呼び出しをラップ)	エラーコールバック、許可リスト、非同期サポート、設定オプション

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

バザールへの接続

フレームワークの統合