Payment Plugins

Payment Plugins

Payment plugins implement the economic transaction layer. Each plugin handles a specific payment rail.

Why payment rails are plugins

The agent economy doesn’t have one payment standard - it has many, and new ones keep appearing. x402 handles HTTP-native payments. Solana escrow handles on-chain task economies. Stripe MPP handles fiat. Tomorrow there will be Lightning, Base, Sui, or something that doesn’t exist yet.

Agent Adapter treats this as a plugin problem, not a core problem. The runtime defines a three-method interface (ensure_secured, settle, refund) and a registry that resolves the right adapter per job. When a new payment rail emerges, integrating it with the runtime is a single plugin - implement the interface, publish the package, add it to the config. The core runtime doesn’t change.

This means providers are never blocked waiting for the runtime to support a new rail. If your platform uses a payment protocol the runtime doesn’t ship with, you write one plugin and every Agent Adapter instance can use it.

Multiple payment adapters coexist in one runtime. The adapter resolves the appropriate one per payment challenge, so a single provider can accept x402 payments from one platform and escrow payments from another, simultaneously.

Interface

Every payment plugin implements the PaymentAdapter contract:

from agent_adapter_contracts.payments import PaymentAdapter

class MyPaymentPlugin(PaymentAdapter):
    async def ensure_secured(self, job) -> bool:
        """Is it economically safe to run this job?"""
        ...

    async def settle(self, job, outcome) -> None:
        """Release or finalize payment."""
        ...

    async def refund(self, job, reason) -> None:
        """Reverse or compensate."""
        ...

Built-in Plugins

payment-free

No-op adapter. All operations succeed immediately. Use for testing and free-tier APIs.

payment-x402

Handles HTTP 402 payment flows:

1. Sends request, receives 402 with payment metadata
2. Signs a payment transaction
3. Retries with proof header

payment-escrow

Generic Solana escrow:

1. Prepares a transaction locking USDC into an escrow PDA
2. Signs and submits
3. Settles or refunds based on outcome

payment-mpp-stripe

Stripe-backed Micropayment Protocol:

1. Creates or joins a payment session
2. Captures charge on completion
3. Supports refunds

Configuration

Each payment plugin is configured in agent-adapter.yaml:

payments:
  - id: "my_payment"
    type: "my_custom_type"
    config:
      apiKey: "${MY_API_KEY}"
      endpoint: "https://pay.example.com"

Publishing

Package your plugin with a pyproject.toml entry point:

[project.entry-points."agent_adapter.payments"]
my_payment = "my_payment_plugin:MyPaymentPlugin"