x402-layerThis skill should be used when the user asks to "create x402 endpoint", "deploy monetized API", "pay for API with USDC", "check x402 credits", "consume API c...
Install via ClawdBot CLI:
clawdbot install ivaavimusic/x402-layerx402 is a Web3 payment layer enabling AI agents to:
Networks: Base (EVM) • Solana
Currency: USDC
Protocol: HTTP 402 Payment Required
pip install -r {baseDir}/requirements.txt# For Base (EVM)
export PRIVATE_KEY="0x..."
export WALLET_ADDRESS="0x..."
# For Solana (optional)
export SOLANA_SECRET_KEY="[1,2,3,...]" # JSON arrayFor Base payments without exposing private keys, use Coinbase Agentic Wallet:
# First, install and set up AWAL (one-time setup)
npx skills add coinbase/agentic-wallet-skills
# Then enable AWAL mode for this skill
export X402_USE_AWAL=1Note: See Coinbase AWAL docs for full setup instructions. You'll need to authenticate and fund your AWAL wallet with USDC on Base.
Once AWAL is configured, all Base payment scripts will automatically use it instead of PRIVATE_KEY.
IMPORTANT: This skill handles private keys for signing blockchain transactions.
>
- Never use your primary custody wallet - Create a dedicated wallet with limited funds
- Private keys are used locally only - They sign transactions locally and are never transmitted
- Signed payloads are sent to api.x402layer.cc - Payment signatures and wallet addresses are transmitted to settle payments
- For testing: Use a throwaway wallet with minimal USDC ($1-5 is enough for testing)
- API Keys: When you create an endpoint, store the returned API key securely
- Review the code: All scripts are auditable in the scripts/ directory
| Script | Purpose |
|--------|---------|
| pay_base.py | Pay for endpoint on Base network |
| pay_solana.py | Pay for endpoint on Solana network |
| consume_credits.py | Use pre-purchased credits (fast) |
| consume_product.py | Purchase digital products (files) |
| awal_cli.py | Run Coinbase Agentic Wallet CLI commands (auth, bazaar, pay, discover) |
| check_credits.py | Check your credit balance |
| recharge_credits.py | Buy credit packs for an endpoint |
| discover_marketplace.py | Browse available services |
| Script | Purpose |
|--------|---------|
| create_endpoint.py | Deploy new monetized endpoint ($1) |
| manage_endpoint.py | View/update your endpoints |
| topup_endpoint.py | Recharge YOUR endpoint with credits |
| list_on_marketplace.py | Update marketplace listing |
| manage_webhook.py | Set/update/remove webhook URL |
[!IMPORTANT]
When you create an endpoint, x402 acts as a proxy to your origin server. You MUST verify that requests are coming from x402.
create_endpoint.py.
x-api-key: <YOUR_API_KEY>If the header is missing or incorrect, reject the request (401 Unauthorized).
[!WARNING]
Credits are NOT test credits! They are consumed with every API request.
User pays $0.01 → Your wallet receives payment → 1 credit deducted from your endpoint| Item | Value |
|------|-------|
| Creation cost | $1 (one-time) |
| Starting credits | 4,000 credits |
| Recharge rate | 500 credits per $1 |
| Consumption | 1 credit per API request |
| Your earnings | Whatever price you set per call |
topup_endpoint.pyYour endpoint stops working and returns an error. Users cannot access it until you recharge.
# Pay with Base (EVM) - 100% reliable
python {baseDir}/scripts/pay_base.py https://api.x402layer.cc/e/weather-data
# Pay with Solana - includes retry logic
python {baseDir}/scripts/pay_solana.py https://api.x402layer.cc/e/weather-data
# Pay with Coinbase Agentic Wallet (AWAL)
python {baseDir}/scripts/awal_cli.py pay-url https://api.x402layer.cc/e/weather-dataPre-purchase credits for instant access without blockchain latency:
# Check your balance
python {baseDir}/scripts/check_credits.py weather-data
# Buy credits (consumer purchasing credits)
python {baseDir}/scripts/recharge_credits.py weather-data pack_100
# Use credits for instant access
python {baseDir}/scripts/consume_credits.py https://api.x402layer.cc/e/weather-data# Browse all services
python {baseDir}/scripts/discover_marketplace.py
# Search by keyword
python {baseDir}/scripts/discover_marketplace.py search weather
# AWAL bazaar discovery
python {baseDir}/scripts/awal_cli.py run bazaar listDeploy your own monetized API:
Basic (not listed on marketplace):
python {baseDir}/scripts/create_endpoint.py my-api "My AI Service" https://api.example.com 0.01 --no-listWith marketplace listing (recommended):
python {baseDir}/scripts/create_endpoint.py my-api "My AI Service" https://api.example.com 0.01 \
--category ai \
--description "AI-powered data analysis API" \
--logo https://example.com/logo.png \
--banner https://example.com/banner.jpgAvailable categories: ai, data, finance, utility, social, gaming
Note: Save the API Key from the output and use it to secure your origin server.
⚠️ IMPORTANT - How Credits Work:
- Cost: $1 one-time, includes 4,000 credits (NOT test credits!)
- Consumption: 1 credit is deducted for each API request to your endpoint
- When credits reach 0: Your endpoint stops working until you recharge
- Recharge: Use topup_endpoint.py to add more credits ($1 = 500 credits)
- Users pay YOU: Each user payment goes to your wallet, then 1 credit is used
Includes 4,000 starting credits.
# List your endpoints
python {baseDir}/scripts/manage_endpoint.py list
# View stats
python {baseDir}/scripts/manage_endpoint.py stats my-api
# Update price
python {baseDir}/scripts/manage_endpoint.py update my-api --price 0.02Your endpoint consumes 1 credit per request. When credits run out, it stops working. Recharge to keep it active:
# Add $10 worth of credits (5,000 credits at 500 credits/$1)
python {baseDir}/scripts/topup_endpoint.py my-api 10
# Check remaining credits first
python {baseDir}/scripts/manage_endpoint.py stats my-api⚠️ Remember: topup_endpoint.py is for providers to recharge THEIR endpoint.
recharge_credits.py is for consumers to buy credits at someone else's endpoint.Marketplace listing can be done during creation OR separately afterward:
Option 1: During Creation (Recommended)
python {baseDir}/scripts/create_endpoint.py my-api "My API" https://api.example.com 0.01 \
--category ai \
--description "AI-powered analysis" \
--logo https://example.com/logo.png \
--banner https://example.com/banner.jpgOption 2: After Creation (Update or List Later)
# List or update marketplace listing
python {baseDir}/scripts/list_on_marketplace.py my-api \
--category ai \
--description "AI-powered analysis" \
--logo https://example.com/logo.png \
--banner https://example.com/banner.jpg
# Unlist from marketplace
python {baseDir}/scripts/list_on_marketplace.py my-api --unlistTip: Use list_on_marketplace.py to update your listing anytime - change category, description, or images without recreating the endpoint.
Receive payment.succeeded events when someone pays for your endpoint. Optional — not required for endpoints to work.
Set webhook at creation time:
python {baseDir}/scripts/create_endpoint.py my-api "My API" https://api.example.com 0.01 \
--webhook-url https://my-server.com/webhookAdd or update webhook on existing endpoint:
python {baseDir}/scripts/manage_webhook.py set my-api https://my-server.com/webhookCheck webhook status:
python {baseDir}/scripts/manage_webhook.py info my-apiRemove webhook:
python {baseDir}/scripts/manage_webhook.py remove my-api⚠️ IMPORTANT: The signing_secret is returned only once when you set a webhook. Save it immediately.
| Event | When | Key Fields |
|-------|------|-----------|
| payment.succeeded | Any payment for your endpoint | amount, tx_hash, payer_wallet, network |
| credits.depleted | Owner credits hit 0 | remaining_credits, topup_endpoint |
| credits.low | Credits drop to ≤100 | remaining_credits |
| credits.recharged | Top-up payment succeeds | credits_added, new_balance, amount_paid |
Your endpoint receives POST requests with:
Content-Type: application/json
X-X402-Event: <event_type>
X-X402-Signature: t=<timestamp>,v1=<hmac_sha256>payment.succeeded example:
{
"id": "event-uuid",
"type": "payment.succeeded",
"created_at": "2026-01-01T00:00:00.000Z",
"data": {
"source": "endpoint",
"source_slug": "my-api",
"amount": 0.01,
"currency": "USDC",
"tx_hash": "0x...",
"payer_wallet": "0x...",
"network": "base",
"status": "confirmed"
}
}credits.depleted example:
{
"type": "credits.depleted",
"data": {
"source": "endpoint",
"source_slug": "my-api",
"remaining_credits": 0,
"message": "Endpoint credits exhausted. Top up to resume service."
}
}credits.recharged example:
{
"type": "credits.recharged",
"data": {
"source": "endpoint",
"source_slug": "my-api",
"credits_added": 5000,
"previous_balance": 0,
"new_balance": 5000,
"amount_paid": 10,
"currency": "USDC"
}
}import hmac, hashlib
def verify(secret, timestamp, body, received_sig):
expected = hmac.new(secret.encode(), f"{timestamp}.{body}".encode(), hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, received_sig)When credits = 0, no requests go through, so no payments happen and no webhook events fire. Self-regulating.
Uses USDC TransferWithAuthorization (EIP-3009):
Uses VersionedTransaction with MessageV0:
extra.feePayer)TransferChecked instruction| Variable | Required For | Description |
|----------|--------------|-------------|
| PRIVATE_KEY | Base payments (private-key mode) | EVM private key (0x...) |
| WALLET_ADDRESS | All operations | Your wallet address |
| SOLANA_SECRET_KEY | Solana payments | JSON array of bytes |
| X402_USE_AWAL | AWAL mode | Set 1 to enable Coinbase Agentic Wallet for Base |
| X402_AUTH_MODE | Auth selection (optional) | auto, private-key, or awal (default: auto) |
| X402_PREFER_NETWORK | Network selection (optional) | base or solana (default: base) |
| AWAL_PACKAGE | AWAL mode (optional) | NPM package/version for AWAL CLI (default: awal@1.0.0) |
| AWAL_BIN | AWAL mode (optional) | Preinstalled awal binary path/name |
| AWAL_FORCE_NPX | AWAL mode (optional) | Set 1 to force npx even when awal binary exists |
https://api.x402layer.cc/e/{slug}https://api.x402layer.cc/api/marketplacehttps://api.x402layer.cc/api/credits/*https://api.x402layer.cc/agent/*⚠️ 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.
Generated Mar 1, 2026
A developer creates a weather API endpoint that charges $0.01 per request using x402. Users pay with USDC on Base or Solana to access real-time weather data, while the provider earns revenue from each call and manages credits through the skill's scripts.
A data analytics firm deploys a monetized API for on-chain analytics, allowing crypto projects to pay per query for custom metrics. They use the marketplace listing feature to attract customers and set up webhooks to receive instant payment notifications.
A content agency offers an AI-powered text generation API priced per token. Customers buy credits upfront via the recharge system, and the agency uses the credit management scripts to monitor usage and top up endpoints as needed.
An IoT company sets up endpoints to sell access to sensor data from devices. They use the skill's consumer scripts to enable pay-per-request or credit-based access, with payments handled securely via USDC on supported networks.
A tech educator creates a coding tutorial API that charges micro-payments for interactive lessons. They leverage the marketplace to list the service and use AWAL mode for simplified payment handling without exposing private keys.
Charge users a small fee (e.g., $0.01) per API call using the pay_base.py or pay_solana.py scripts. This model is ideal for services with variable usage, as it directly ties revenue to consumption without upfront commitments.
Sell credit packs via recharge_credits.py, where users prepay for a bundle of API calls (e.g., 500 credits per $1). This provides predictable cash flow and simplifies billing, with credits deducted per request using consume_credits.py.
List your endpoint on the x402 marketplace using list_on_marketplace.py to attract users, then charge premium rates for specialized data or features. Combine with webhooks for real-time payment tracking and management.
💬 Integration Tip
Start with a test wallet and minimal USDC to validate the payment flow, then implement API key verification on your origin server to ensure security.
Connect Claude to Clawdbot instantly and keep it connected 24/7. Run after setup to link your subscription, then auto-refreshes tokens forever.
ERC-8004 Trustless Agents - Register, discover, and build reputation for AI agents on Ethereum. Use when registering agents on-chain, querying agent registries, giving/receiving reputation feedback, or interacting with the AI agent trust layer.
Autonomous crypto trading on Base via Bankr. Use for trading tokens, monitoring launches, executing strategies, or managing a trading portfolio. Triggers on "trade", "buy", "sell", "launch", "snipe", "profit", "PnL", "portfolio balance", or any crypto trading task on Base.
Deploy ERC20 tokens on Base using Clanker SDK. Create tokens with built-in Uniswap V4 liquidity pools. Supports Base mainnet and Sepolia testnet. Requires PRIVATE_KEY in config.
Query DeFi portfolio data across 50+ chains via Zapper's GraphQL API. Use when the user wants to check wallet balances, DeFi positions, NFT holdings, token prices, or transaction history. Supports Base, Ethereum, Polygon, Arbitrum, Optimism, and more. Requires ZAPPER_API_KEY.
Interact with Solana blockchain via Helius APIs. Create/manage wallets, check balances (SOL + tokens), send transactions, swap tokens via Jupiter, and monitor addresses. Use for any Solana blockchain operation, crypto wallet management, token transfers, DeFi swaps, or portfolio tracking.