Agentcore X402 Payments For Openclaw

Name: Agentcore X402 Payments For Openclaw
Rating: 3.5 (1 reviews)
Author: wirjo

By wirjo ⭐ 1 stars 👁 4 views ▲ 0 votes

Native OpenClaw plugin for transparent x402 paywall auto-pay via AWS AgentCore Payments

GitHub

Install

npm install
npx

Configuration Example

{
  "plugins": {
    "entries": {
      "x402-payments": {
        "config": {
          "region": "us-east-1",
          "paymentManagerArn": "arn:aws:bedrock-agentcore:us-east-1:ACCOUNT_ID:payment-manager/YOUR_PM_ID",
          "paymentInstrumentId": "YOUR_INSTRUMENT_ID",
          "userId": "your-user-id",
          "networkPreferences": ["eip155:84532"]
        }
      }
    }
  }
}

README

# x402 Payments for OpenClaw

Native [OpenClaw](https://openclaw.ai) plugin for transparent x402 paywall auto-pay via [AWS AgentCore Payments](https://docs.aws.amazon.com/bedrock-agentcore/latest/userguide/).

When an AI agent encounters an HTTP 402 (x402 paywall), this plugin transparently pays using a Coinbase CDP wallet managed by AWS AgentCore — the agent gets the content without needing to understand crypto.

## Installation

```bash
openclaw plugins install clawhub:@aws/openclaw-x402-payments
```

## Configuration

Add to your `~/.openclaw/openclaw.json`:

```json
{
  "plugins": {
    "entries": {
      "x402-payments": {
        "config": {
          "region": "us-east-1",
          "paymentManagerArn": "arn:aws:bedrock-agentcore:us-east-1:ACCOUNT_ID:payment-manager/YOUR_PM_ID",
          "paymentInstrumentId": "YOUR_INSTRUMENT_ID",
          "userId": "your-user-id",
          "networkPreferences": ["eip155:84532"]
        }
      }
    }
  }
}
```

Then restart OpenClaw:

```bash
openclaw gateway restart
```

## First-Time Setup

If you don't have AgentCore Payments infrastructure yet, the plugin includes a `setup_x402_payments` tool that creates everything in one shot. Just ask your agent:

> "Set up x402 payments for me"

The agent will guide you through:
1. Getting a Coinbase CDP API key from [portal.cdp.coinbase.com](https://portal.cdp.coinbase.com)
2. Creating the payment infrastructure (Payment Manager → Connector → Wallet)
3. Funding your wallet with testnet USDC

## Tools

| Tool | Description |
|------|-------------|
| `setup_x402_payments` | One-shot infrastructure setup (CDP key → full payment stack) |
| `get_payment_session_status` | Check current session usability |
| `create_payment_session` | Mint a new session (locks USDC up to spend cap) |
| `get_paid_content` | Probe → pay → fetch paywalled content server-side |
| `pay_and_get_header` | Probe → pay → return header for browser replay |

## How It Works

1. Agent fetches a URL → gets HTTP 402 with x402 challenge
2. Plugin extracts the payment challenge (base64 JSON in headers)
3. Calls AWS AgentCore `ProcessPayment` with the challenge
4. AgentCore signs the payment via Coinbase CDP wallet
5. Plugin replays the request with the signed `X-PAYMENT` header
6. Returns the paid content to the agent

## Architecture

```
Agent → get_paid_content(url)
         ├── Probe URL → 402 + challenge
         ├── ProcessPayment(challenge) → signed header
         │     └── AWS AgentCore → Coinbase CDP → EVM signature
         ├── Sleep past validAfter (EVM clock skew)
         └── Replay with X-PAYMENT header → 200 + content
```

## Prerequisites

- AWS account with AgentCore Payments enabled
- AWS credentials available (instance role, env vars, or profile)
- Coinbase CDP API key (from [portal.cdp.coinbase.com](https://portal.cdp.coinbase.com))
- Funded wallet (Base Sepolia USDC for testnet; fund at [faucet.circle.com](https://faucet.circle.com))

## Development

### Build

```bash
npm install
npx tsc
```

### Validate

```bash
clawhub package validate .
```

### Test locally

```bash
# Link the plugin locally for development
openclaw plugins link .

# Restart to load
openclaw gateway restart

# Verify tools registered
openclaw plugins inspect x402-payments --runtime
```

## Publishing to ClawHub

### Prerequisites

1. Install ClawHub CLI: `npm install -g clawhub`
2. Authenticate: `clawhub auth login`
3. Ensure you have publisher access (e.g., `@aws`)

### Validate before publishing

```bash
clawhub package validate .
```

This runs the Plugin Inspector and reports any breakages or warnings.

### Publish

```bash
clawhub package publish . \
  --family code-plugin \
  --owner aws \
  --display-name "x402 Payments" \
  --source-repo wirjo/agentcore-x402-payments-for-openclaw \
  --changelog "Your changelog message here"
```

### Dry run (preview without publishing)

```bash
clawhub package publish . \
  --family code-plugin \
  --owner aws \
  --display-name "x402 Payments" \
  --source-repo wirjo/agentcore-x402-payments-for-openclaw \
  --changelog "..." \
  --dry-run
```

### Version bumps

ClawHub enforces immutable versions. Bump in `package.json` before each publish:

```bash
npm version patch  # 1.0.0 → 1.0.1
npm version minor  # 1.0.1 → 1.1.0
npm version major  # 1.1.0 → 2.0.0
```

## Bundled Skill

The plugin includes a skill at `skills/x402-payments/SKILL.md` that teaches the agent:
- When and how to trigger payment flows
- The full payment protocol (probe → pay → replay)
- Error handling and session management
- Security considerations (user approval before spending)

## License

Apache-2.0

## Links

- [ClawHub Package](https://clawhub.ai/packages/@aws/openclaw-x402-payments)
- [OpenClaw Documentation](https://docs.openclaw.ai)
- [AWS AgentCore Payments](https://docs.aws.amazon.com/bedrock-agentcore/latest/userguide/)
- [x402 Protocol](https://www.x402.org/)

tools