X402

Name: X402
Rating: 3.5 (1 reviews)
Author: ElliotPadfield

By ElliotPadfield ⭐ 1 stars 👁 1 views ▲ 0 votes

OpenClaw plugin for discovering and calling x402-paid APIs

GitHub

Install

npm install
npm

Configuration Example

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

README

# @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:

```bash
openclaw plugins install @elliotpadfield/openclaw-x402
```

From a local tarball while developing:

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

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

```bash
openclaw plugins list
openclaw plugins info openclaw-x402
```

## Setup

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

Minimal example:

```json
{
  "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:

```bash
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:

```bash
export OPENCLAW_X402_EVM_PRIVATE_KEY=0x...
export OPENCLAW_X402_SVM_PRIVATE_KEY=...
```

If you want custom env var names:

```json
{
  "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:

```json
{
  "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](./.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:

```bash
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:

```text
<workspace>/.openclaw-x402/
```

This includes:

- `receipts.jsonl`
- `imports/*.json`

## Development

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

See [CONTRIBUTING.md](./CONTRIBUTING.md) for local install and smoke-test steps.

## License

Apache-2.0. See [LICENSE](./LICENSE).

voice