@elliotpadfield/openclaw-x402

Installable OpenClaw plugin for discovering and calling x402-paid HTTP APIs.

This plugin fits the existing OpenClaw ecosystem:

• install it as a standard OpenClaw plugin
• let the agent use x402_fetch for payable HTTP calls
• use x402_openapi_import to inspect OpenAPI specs and save local API indexes
• use x402_api_search to search configured x402 services and imported APIs
• optionally bundle planner guidance via the included x402 skill

It does not rewrite every other plugin's HTTP stack. It makes x402 work through its own tools without needing OpenClaw core changes.

Status

Alpha.

What is already proven:

• loads as an OpenClaw plugin
• registers tools correctly
• handles 402 -> sign -> retry with Coinbase's x402 libraries
• works against a real public x402 endpoint

What is not fully proven yet:

• end-to-end settlement with a funded wallet against multiple public services
• automatic generation of first-class OpenClaw tools from imported OpenAPI specs

Ecosystem Shape

This package is structured to match how current OpenClaw plugins are distributed:

• published to npm
• installable with openclaw plugins install <npm-spec>
• public source repo with docs and issue tracker
• package metadata compatible with OpenClaw's plugin loader

That matches the current OpenClaw community plugin guidance and the shape used by published packages like @openclaw/voice-call and @icesword760/openclaw-wechat.

Install

From npm:

openclaw plugins install @elliotpadfield/openclaw-x402

From a local tarball while developing:

npm pack
openclaw plugins install ./openclaw-x402-0.1.1.tgz

Installed plugins are enabled by default. You can verify load status with:

openclaw plugins list
openclaw plugins info openclaw-x402

Setup

OpenClaw plugin config belongs under plugins.entries.openclaw-x402.config.

Minimal example:

{
  "plugins": {
    "entries": {
      "openclaw-x402": {
        "enabled": true,
        "config": {
          "defaultBudgetUsd": 5,
          "approvalThresholdUsd": 0.25,
          "allowedNetworks": ["eip155:8453", "eip155:84532"],
          "allowedDomains": ["api.example.com", "*.x402.org"]
        }
      }
    }
  }
}

You can also set it through the CLI:

openclaw config set plugins.entries.openclaw-x402.enabled true --json
openclaw config set plugins.entries.openclaw-x402.config.defaultBudgetUsd 5 --json
openclaw config set plugins.entries.openclaw-x402.config.approvalThresholdUsd 0.25 --json
openclaw config set plugins.entries.openclaw-x402.config.allowedNetworks '["eip155:8453"]' --json

Signer env vars:

export OPENCLAW_X402_EVM_PRIVATE_KEY=0x...
export OPENCLAW_X402_SVM_PRIVATE_KEY=...

If you want custom env var names:

{
  "plugins": {
    "entries": {
      "openclaw-x402": {
        "enabled": true,
        "config": {
          "evmPrivateKeyEnv": "MY_X402_EVM_KEY",
          "svmPrivateKeyEnv": "MY_X402_SVM_KEY"
        }
      }
    }
  }
}

Restart the Gateway after config changes.

Configuration

Supported config fields:

• stateDir: override the default state directory
• evmPrivateKeyEnv: env var name used for the EVM signer
• svmPrivateKeyEnv: env var name used for the SVM signer
• defaultBudgetUsd: hard budget for cumulative spend
• approvalThresholdUsd: requests above this are blocked
• allowUnknownAssets: allow payment requirements without a usable USD estimate
• allowPrivateHosts: allow localhost and private network targets
• maxResponseBytes: response body cap
• defaultTimeoutMs: default request timeout
• allowedDomains: outbound domain allowlist
• allowedNetworks: x402 network allowlist
• allowedPayees: payee allowlist
• registry: static list of known x402 services for x402_api_search

Example registry entry:

{
  "plugins": {
    "entries": {
      "openclaw-x402": {
        "enabled": true,
        "config": {
          "registry": [
            {
              "id": "spraay",
              "name": "Spraay Gateway",
              "baseUrl": "https://gateway.spraay.app",
              "docsUrl": "https://github.com/plagtech/spraay-x402-gateway",
              "description": "Public x402 gateway",
              "tags": ["ai", "gateway", "search"]
            }
          ]
        }
      }
    }
  }
}

See .env.example for a starter env file.

Tools

x402_fetch

Calls an arbitrary HTTP endpoint. If the endpoint returns 402 Payment Required and policy allows it, the plugin signs the payment payload with Coinbase's x402 SDKs, retries the request, and stores a receipt.

Payment status is explicit:

• payment.attempted: false: no x402 flow happened
• payment.attempted: true and payment.paid: false: retry happened, but the remote service still rejected payment
• payment.attempted: true and payment.paid: true: payment retry succeeded

x402_openapi_import

Fetches or parses an OpenAPI document, summarizes operations, and optionally saves an import snapshot into the plugin state directory.

x402_api_search

Searches configured registry entries plus locally saved imports.

External Smoke Test

As of March 7, 2026, this public endpoint returns a real x402 402 Payment Required response when called without a valid funded signer:

• https://gateway.spraay.app/api/v1/models

Raw curl check:

curl -i https://gateway.spraay.app/api/v1/models

Expected result:

• HTTP 402
• a PAYMENT-REQUIRED header

Plugin behavior with a throwaway unfunded EVM key:

• the plugin reaches the public endpoint
• parses the x402 requirement
• signs and retries
• the server rejects with 402 insufficient_funds
• the plugin returns payment.attempted: true and payment.paid: false

This is a safe public smoke test because no funded wallet is required.

State

By default the plugin stores state under:

<workspace>/.openclaw-x402/

This includes:

• receipts.jsonl
• imports/*.json

Development

npm install
npm run typecheck
npm test
npm pack --dry-run

See CONTRIBUTING.md for local install and smoke-test steps.

License

Apache-2.0. See LICENSE.