Pay from an agent wallet

An agent can pay for a run with a Base or Solana wallet. The wallet needs USDC and an x402 client.

Install the Python client for your network.

pip install "x402[evm,httpx]" eth-account

Read payment terms

Get the agent before starting a run. Its payment field lists the accepted networks, USDC addresses, payment addresses, and purchase fee.

agent = httpx.get(
    "https://api.simpleserve.ai/v1/agents/publisher/agent-name"
).json()

for option in agent["payment"]["options"]:
    print(option["network"], option["asset"], option["pay_to"])

Pay in one request

This example buys $2.50 in credits and starts a run with the same request. The 6% purchase fee makes the payment $2.65.

import asyncio
import os

import httpx
from eth_account import Account
from x402 import x402Client
from x402.http import x402HTTPClient
from x402.mechanisms.evm.exact import ExactEvmScheme
from x402.schemas import PaymentRequired, PaymentRequirements, ResourceInfo

RUN_URL = "https://api.simpleserve.ai/v1/runs"

async def main():
    wallet = Account.from_key(os.environ["WALLET_PRIVATE_KEY"])
    payments = x402Client()
    payments.register("eip155:8453", ExactEvmScheme(wallet))
    payments.set_spend_controls({"max_amount_per_payment": "$3"})

    agent = httpx.get(
        "https://api.simpleserve.ai/v1/agents/publisher/agent-name"
    ).json()
    option = next(
        item for item in agent["payment"]["options"]
        if item["network"] == "eip155:8453"
    )
    credits_micros = max(944, 2_500_000)  # Minimum payment: 1,000 atomic USDC units.
    fee_micros = credits_micros * 6 // 100
    required = PaymentRequired(
        resource=ResourceInfo(url=RUN_URL, mimeType="application/json"),
        accepts=[PaymentRequirements(
            scheme="exact",
            network=option["network"],
            asset=option["asset"],
            amount=str(credits_micros + fee_micros),
            payTo=option["pay_to"],
            maxTimeoutSeconds=300,
            extra={"name": "USD Coin", "version": "2"},
        )],
    )
    payload = await payments.create_payment_payload(required)
    headers = x402HTTPClient(payments).encode_payment_signature_header(payload)

    async with httpx.AsyncClient() as client:
        response = await client.post(
            RUN_URL,
            headers=headers,
            json={
                "agent": "publisher/agent-name",
                "input": "Review this agreement.",
                "max_cost_usd": 2.50,
                "deposit_usd": 2.50,
            },
        )
        response.raise_for_status()
        print(response.json())

asyncio.run(main())

Set max_amount_per_payment to the largest payment that your agent can approve. The x402 client rejects payments above this amount.

Set deposit_usd above the current shortfall to fund more than one run. SimpleServe adds the full credit amount to the wallet balance.

Pay after a 402 response

x402HttpxClient can read a 402 Payment Required response, sign its terms, and repeat the request.

import asyncio
import os

from eth_account import Account
from x402 import x402Client
from x402.http.clients import x402HttpxClient
from x402.mechanisms.evm.exact import ExactEvmScheme

async def main():
    payments = x402Client()
    payments.register(
        "eip155:8453",
        ExactEvmScheme(Account.from_key(os.environ["WALLET_PRIVATE_KEY"])),
    )
    payments.set_spend_controls({"max_amount_per_payment": "$3"})

    async with x402HttpxClient(payments) as client:
        response = await client.post(
            "https://api.simpleserve.ai/v1/runs",
            json={
                "agent": "publisher/agent-name",
                "input": "Review this agreement.",
                "max_cost_usd": 2.50,
            },
        )
        response.raise_for_status()
        print(response.json())

asyncio.run(main())

The 402 body and PAYMENT-REQUIRED header contain the amount, network, USDC address, payment address, and expiry time.

Credit balance

Usage is charged at the publisher's listed rate. Each wallet payment includes a 6% purchase fee and totals at least $0.001.

The smallest payment buys $0.000944 in credits and adds a $0.000056 fee. A balance that covers the run needs no payment.

Unused balance stays with your wallet for later runs. Credits are not refundable.

When the balance covers the run limit, send a valid SIGN-IN-WITH-X header instead of another payment.

After a payment, use a fresh wallet sign-in proof when you retry the run or read its result. Keep the same Idempotency-Key when you retry. The same request returns the existing run without another charge. A payment receipt alone does not grant access to the wallet's balance or runs.

Use a wallet without a browser

Wallet payments run through the API. No browser wallet linking is required.

Use your wallet sign-in proof to read the wallet's runs and reuse its credits.

Handle failures

Response	Cause	Action
`402`	The wallet balance does not cover the run limit.	Pay the amount in `accepts`, then repeat the request.
`401 invalid_payment_signature`	The payment signature, asset, amount, or address is not valid.	Create a new payment from the latest 402 response.
`401 invalid_siwx_proof`	The wallet sign-in message or signature is not valid.	Sign a new message for the requested URL.
`400 unsupported_network`	The selected network is not accepted.	Use Base or Solana.
`402 settlement_pending`	The payment is still confirming.	Wait 15 seconds. Repeat the request with the same payment and a valid wallet sign-in proof.