OpenClaw x402-Layer Skill

Production-ready skill for OpenClaw agents to interact with x402 Singularity Layer.

✅ Tested with real payments on Base (EVM) and Solana networks

Wallet-first ERC-8004 agent flows also support EVM deployments on Ethereum, Polygon, BSC, and Monad through the same scripts by changing --network.

View full source code for all scripts in our GitHub Repository.

Quick Start

v1.4.0 adds wallet-first ERC-8004 discovery and management scripts alongside registration.

Install via the self-hosted skill endpoint:

curl -fsSL https://api.x402layer.cc/skill/x402-layer/install | bash

# Or specify a custom directory
curl -fsSL https://api.x402layer.cc/skill/x402-layer/install | bash -s ./my-skills/x402-layer

Or view the skill manifest for manual installation.

Environment Setup

Choose Option A (private keys) or Option B (Coinbase Agentic Wallet):

# Option A: Private Keys (traditional mode)
# For Base (EVM) - Recommended for full control
export PRIVATE_KEY="0x..."
export WALLET_ADDRESS="0x..."

# For Solana (Optional)
export SOLANA_SECRET_KEY="base58-or-[1,2,3,...]"  # base58 secret or JSON array
export SOLANA_WALLET_ADDRESS="..."

# Option B: Coinbase Agentic Wallet (AWAL) - No private key exposure
# First install the Coinbase skill
npx skills add coinbase/agentic-wallet-skills

# Then enable AWAL mode
export X402_USE_AWAL=1
export WALLET_ADDRESS="0x..."  # Still needed for identification

# Agentic feedback
export WORKER_FEEDBACK_API_KEY="..."

🔐 AWAL Mode (hardened in v1.3.1)

Use Coinbase Agentic Wallet for Base payments without exposing private keys. Perfect for production agents where key security is critical.

Skill API Endpoints

Access individual files directly via our API:

Endpoint	Description
/skill/x402-layer	JSON manifest with file list
/skill/x402-layer/install	Shell install script
/skill/x402-layer/SKILL.md	Main skill instructions
/skill/x402-layer/requirements.txt	Python dependencies
/skill/x402-layer/scripts/{name}	Individual script files (.py and .js)

Available Scripts

🛒 Consumer Mode (Buying Services)

Script	Purpose
pay_base.py	Pay for endpoints on Base (100% reliable)
pay_solana.py	Pay for endpoints on Solana (with retry)
consume_credits.py	Use pre-purchased credits (fastest)
consume_product.py	Purchase digital products (files)
check_credits.py	Check your credit balance
recharge_credits.py	Buy credit packs
discover_marketplace.py	Browse available services

🏭 Provider Mode (Selling Services)

Script	Purpose
create_endpoint.py	Deploy new endpoint ($1 fee)
manage_endpoint.py	View/update your endpoints
topup_endpoint.py	Add credits to YOUR endpoint
list_on_marketplace.py	Publish endpoint publicly
manage_webhook.py	Set/update/remove endpoint webhook
verify_webhook_payment.js	Verify webhook signature + payment receipt genuineness using x402sgl

🪪 Agent Identity & Reputation

Script	Purpose
register_agent.py	Register ERC-8004 (EVM/Solana) with image, version, tags, and endpoint bindings
list_my_endpoints.py	List platform endpoints available for ERC-8004 agent binding
list_agents.py	List ERC-8004 agents owned by the wallet or linked dashboard user
update_agent.py	Update metadata, visibility, and endpoint bindings for an existing agent
submit_feedback.py	Write on-chain reputation feedback on the agent's native chain

Usage Examples

Pay for an Endpoint

# Pay with Base (recommended - 100% success rate)
python scripts/pay_base.py https://api.x402layer.cc/e/weather-data

# Pay with Solana (includes retry logic)
python scripts/pay_solana.py https://api.x402layer.cc/e/weather-data

# Pay with AWAL (no private key needed)
export X402_USE_AWAL=1
python scripts/pay_base.py https://api.x402layer.cc/e/weather-data

Use Credits (Fastest)

# Check balance
python scripts/check_credits.py weather-data

# Buy credits
python scripts/recharge_credits.py weather-data pack_100

# Consume with credits (zero blockchain latency)
python scripts/consume_credits.py https://api.x402layer.cc/e/weather-data

Create Your Own Endpoint

# Deploy a monetized endpoint ($1 one-time fee)
python scripts/create_endpoint.py my-api "My AI Service" https://api.example.com 0.01

# Top up YOUR endpoint with credits
python scripts/topup_endpoint.py my-api 10  # Add $10 worth

# List on marketplace
python scripts/list_on_marketplace.py my-api --category ai --description "AI analysis"

Verify Webhook Payment Genuineness (x402sgl)

# Install SDK once
npm install x402sgl
pip install "git+https://github.com/ivaavimusic/Singularity-SDK.git#subdirectory=python"

# Verify webhook signature + receipt token
node scripts/verify_webhook_payment.js \
  --body-file ./webhook.json \
  --signature 't=1700000000,v1=<hex>' \
  --secret '<YOUR_SIGNING_SECRET>' \
  --required-source-slug my-api \
  --require-receipt

ERC-8004 Registration, Discovery, and Management

python scripts/list_my_endpoints.py

python scripts/register_agent.py \
  "My Agent" \
  "Autonomous service agent" \
  --network baseSepolia \
  --image https://example.com/agent.png \
  --version 1.4.0 \
  --tag finance \
  --endpoint-id <ENDPOINT_UUID> \
  --custom-endpoint https://api.example.com/agent

python scripts/list_agents.py --network baseSepolia

python scripts/update_agent.py \
  --network baseSepolia \
  --agent-id 123 \
  --version 1.4.1 \
  --tag finance \
  --endpoint-id <ENDPOINT_UUID> \
  --public

# The same EVM flow also supports:
#   --network ethereum
#   --network polygon
#   --network bsc
#   --network monad

python scripts/submit_feedback.py

🔐 Security: API Key Verification

When you create an endpoint, x402 acts as a proxy. You MUST verify requests are coming from x402.

Get API Key: Saved from create_endpoint.py output.
Verify Headers: Check for x-api-key: YOUR_KEY in every request.

Known Issues

⚠️ Solana payments have ~75% success rate due to facilitator-side fee payer infrastructure issue. Retry logic is included in pay_solana.py.

Base (EVM) payments are 100% reliable and recommended for production.

Skill Metadata

Slug	x402-layer
Version	1.3.1
Networks	Base (EVM), Solana
Currency	USDC