Documentation Index

Fetch the complete documentation index at: https://docs.x402layer.cc/llms.txt

Use this file to discover all available pages before exploring further.

​

OpenClaw x402-Layer Skill

​

Script Source Code

​

Quick Start

​

Installation

# One-line installer (recommended)
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

git clone https://github.com/ivaavimusic/x402-Layer-Clawhub-Skill.git
cd x402-Layer-Clawhub-Skill/scripts
pip install -r ../requirements.txt

​

Environment Setup

# Read-only discovery needs no secrets
python scripts/discover_marketplace.py

# For Base (EVM) - Recommended
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

npx skills add coinbase/agentic-wallet-skills
export X402_USE_AWAL=1

npm install -g @open-wallet-standard/core
export OWS_WALLET="hackathon-wallet"
python scripts/ows_cli.py pay-url https://api.x402layer.cc/e/weather-data --wallet hackathon-wallet

export SINGULARITY_PAT="sgl_pat_..."

export X_API_KEY="x402_..."
python scripts/manage_campaign.py list
python scripts/manage_campaign.py create --title "My Campaign" --wallet <SOLANA_WALLET> --target 1000

Studio seller webhooks use X-X402-Signature, X-X402-Timestamp, X-X402-Event, and X-X402-Event-Id. Verify HMAC-SHA256(timestamp + "." + rawBody) with the webhook signing_secret. Keep legacy raw-secret headers only as fallback for older receivers, and do not confuse the Studio signing secret with any app-internal settlement secret such as x-x402-secret → X402_WEBHOOK_SECRET.

​

World AgentKit Benefits

# Inspect whether an endpoint advertises a verified human-backed agent wallet benefit
python scripts/discover_marketplace.py details weather-data

# Attempt Base payment with AgentKit if the endpoint offers it
python scripts/pay_base.py https://api.x402layer.cc/e/weather-data --agentkit auto

# Require AgentKit qualification instead of silently falling back
python scripts/pay_base.py https://api.x402layer.cc/e/weather-data --agentkit required

​

XMTP Support Threads

# Authenticate your wallet for support APIs
python scripts/support_auth.py login

# Check support eligibility and open or reuse a support thread
python scripts/support_threads.py eligibility endpoint weather-data
python scripts/support_threads.py open endpoint weather-data

# Read and send XMTP support messages
node scripts/xmtp_support.mjs messages <thread_id>
node scripts/xmtp_support.mjs send <thread_id> "Need help with this endpoint"

​

Usage Examples

​

Integrate Payments Into Your App

# 1. Create or reuse a paid endpoint
python scripts/create_endpoint.py my-api "My AI Service" https://api.example.com 0.01

# 2. Add webhook-based fulfillment
python scripts/manage_webhook.py set my-api https://my-server.com/webhook

# 3. Verify the webhook signature + receipt server-side
python scripts/verify_webhook_payment.py \
  --body-file ./webhook.json \
  --signature 't=1700000000,v1=<hex>' \
  --secret '<YOUR_SIGNING_SECRET>' \
  --required-source-slug my-api \
  --require-receipt

​

Pay for an Endpoint (Consumer)

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

# Pay with Solana (PayAI-backed sponsored flow)
python scripts/pay_solana.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 (Provider)

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

Note: Save the API Key from the output and use it to secure your origin server.

​

Add API Schema Documentation

# Attach schema at creation
python scripts/create_endpoint.py my-api "My API" https://api.example.com 0.01 \
  --schema-file schema.json

# Update schema on existing endpoint
python scripts/manage_endpoint.py update my-api --schema-file updated-schema.json

# Clear schema
python scripts/manage_endpoint.py update my-api --clear-schema

• Displays on marketplace listings
• Is included in 402 challenge responses for programmatic discovery
• Powers the interactive API tester on hosted pay pages

​

Security: API Key Verification

[!IMPORTANT] When you create an endpoint, x402 acts as a proxy to your origin server. You MUST verify requests are coming from x402.

1. Get your API Key: Returned when you run create_endpoint.py.
2. Verify Headers: Your origin server MUST check for this header in every request:
   x-api-key: <YOUR_API_KEY>
   
   If the header is missing or incorrect, reject the request (401 Unauthorized).

# 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-powered analysis"

​

Browse Marketplace

# List all services
python scripts/discover_marketplace.py

# Search by keyword
python scripts/discover_marketplace.py search weather

# Get featured endpoints
python scripts/discover_marketplace.py featured

​

Register an Agent (Wallet-First)

# Discover bindable endpoints first
python scripts/list_my_endpoints.py

# Default wallet-first registration with rich metadata
python scripts/register_agent.py \
  "My Agent" \
  "Autonomous service agent" \
  --network baseSepolia \
  --image https://example.com/agent.png \
  --version 1.10.0 \
  --tag finance \
  --tag automation \
  --endpoint-id <ENDPOINT_UUID> \
  --custom-endpoint https://api.example.com/agent

# List owned agents
python scripts/list_agents.py --network baseSepolia

# Update an existing agent
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

1. register_agent.py requests a one-time challenge from POST /agent/auth/challenge
2. Your wallet signs the challenge locally
3. The script exchanges that signature at POST /agent/auth/verify
4. The worker returns a short-lived session token
5. list_my_endpoints.py and list_agents.py use wallet-authenticated GET /agent/erc8004/endpoints/mine and GET /agent/erc8004/mine
6. The same wallet sends the real on-chain transaction via prepare/finalize routes
7. update_agent.py uses update/prepare plus update/finalize, and automatically sends the on-chain URI update transaction when metadata changes

​

Technical Details

​

Base (EVM) Payments

• Gasless for the payer
• Facilitator settles on-chain
• Simplest production default

​

Solana Payments

• Facilitator pays gas fees
• SPL Token TransferChecked instruction
• Must include the live feePayer from the challenge
• Exact-payment payload must stay within facilitator compute limits
• The bundled signer handles the current live flow

​

Skill Metadata

​

Resources

• OpenClaw on X
• x402 Studio Dashboard
• Marketplace
• GitHub Repository

​

Changelog

​

v1.12.0

• Added API schema support for endpoint route documentation (--schema-file, --schema-json, --clear-schema)
• Schema displays on marketplace listings, 402 challenge responses, and hosted pay page API testers
• Agents can self-discover available routes from the 402 challenge or management API before paying
• Fixed worker skill version mismatch (was 1.10.6 in worker vs 1.11.1 in SKILL.md)

​

v1.10.3

• added optional OpenWallet / OWS support for pay, discover, and sign-message flows
• added a dedicated ows_cli.py wrapper plus OpenWallet guidance
• kept private-key and AWAL flows intact while expanding wallet backend options

​

v1.9.1

• hardened xmtp_support.mjs by removing the environment-driven Studio base override from the helper itself
• added explicit runbooks for World AgentKit benefits and XMTP support thread operations
• refreshed stale example versions and kept MCP guidance in the same install surface

​

v1.8.2

• removed globally-required secret env declarations from skill metadata
• documented capability-specific environment requirements so users expose only the vars needed for the current task
• synced the safer environment guidance across the hosted skill and public docs

​

v1.8.1

• fixed direct Base endpoint payments for skill usage by rejecting self-payment early
• aligned pay_base.py with the hosted purchase-path shape using ?action=purchase

​

v1.8.0

• Added seller-side endpoint configuration parity for best-fit audience and verified human-backed AgentKit benefit fields
• Added real manage_endpoint.py update support against worker PATCH routes

​

v1.7.0

• Added wallet-signed support APIs for agent wallets
• Added support thread commands and XMTP helper flows for agent-side support operations
• Preserved AgentKit-aware discovery and optional Base payment flow for verified human-backed agent wallets

​

v1.5.0

• Added a first-class payments integration path for agents using direct endpoints, credits, products, webhooks, and receipt verification
• Added payments-integration.md as the decision guide for payment shape and fulfillment strategy
• Fixed the bundled Solana signer to match the live PayAI-backed compute limit requirement

​

v1.4.0

• Wallet-first ERC-8004 / Solana-8004 registration is now the default for register_agent.py
• Added signed challenge + short-lived agent session flow for API-only wallet auth
• Added list_my_endpoints.py, list_agents.py, and update_agent.py for full post-registration lifecycle management
• Registration now supports version, tags, platform endpoint bindings, and custom endpoint URLs
• Removed the legacy x402-paid worker registration path; wallet-first registration is now the only supported agent flow

​

v1.0.1

• New Script: consume_product.py - Purchase and download digital products

​

v1.0.0

• Deploy monetized endpoints with automatic wallet-to-wallet profit routing
• Top up credits programmatically
• List endpoints on public marketplace

• Marketplace discovery with filtering
• Pay-per-request with EIP-712 permits (Base) and VersionedTransaction (Solana)
• Credit-based access for zero-latency consumption