Skill: x402 Singularity Layer

Owner: ivaavimusic

Summary: This 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...

Tags: ERC8004:1.2.0, SGL:1.2.1, Stripe:1.2.1, agentic:1.1.3, agentic access:1.2.1, agentic webhooks:1.2.1, api:1.2.1, awal:1.1.1, base:1.2.1, coinbase:1.1.1, credits:1.2.1, latest:1.2.1, marketplace:1.2.1, monetization:1.2.1, payments:1.2.1, solana:1.2.1, stripe:1.2.0, usdc:1.2.1, web3:1.2.1, x402:1.2.1, x402 Bazaar:1.2.0, x402 Protocol:1.2.1, x402 Singularity Layer:1.2.1

Version history:

v1.2.1 | 2026-02-27T13:19:27.315Z | user

v1.2.1 (2026-02-27)

Agentic Webhooks Expanded from 1 to 4 event types

Event Types

• payment.succeeded Fires on any payment for your endpoint (unchanged)

• credits.depleted Fires when endpoint.owner_credits hits 0 Signals that a top-up is required before users receive 503 errors

• credits.low Fires when credits drop to 100 or below Early warning to top up proactively

• credits.recharged Fires after a successful top-up Returns credits_added, previous_balance, new_balance

Technical

• Refactored dispatchEndpointWebhook to a generic (eventType, data) signature
• credits.depleted and credits.low fire at the per-request deduction site (post-RPC)
• credits.recharged fires alongside payment.succeeded on the top-up path
• All events use the same HMAC-SHA256 signing as payment.succeeded

Documentation

• SKILL.md updated with an event type table and example payloads

v1.2.0 | 2026-02-27T09:03:06.877Z | user

v1.2.0 (2026-02-27)

NEW: Agentic Webhooks - endpoint-level payment notifications

• Agents can now receive payment.succeeded events at their own HTTPS URL
• No user account or Pro plan required - works purely via API key
• Webhook fires on: credit purchase, direct payment, top-up

NEW SCRIPT: manage_webhook.py

• manage_webhook.py set <slug> <url> — add or update webhook
• manage_webhook.py remove <slug> — remove webhook
• manage_webhook.py info <slug> — check if webhook is configured

UPDATED: create_endpoint.py

• New --webhook-url flag: set a webhook at endpoint creation time
• Returns signing_secret in response (shown once, save immediately)

Backend API:

• POST /agent/endpoints: add webhook_url in body
• PATCH /agent/endpoints?slug=X: set/update/remove webhook after creation Requires: X-API-Key header (from creation response) Body: {"webhook_url": "https://..."} or {"webhook_url": null}

Webhook signature verification: HMAC-SHA256 over "timestamp.body" using your signing_secret Header: X-X402-Signature: t=<ts>,v1=<hex>

Event format: { "id": "<uuid>", "type": "payment.succeeded", "created_at": "<iso8601>", "data": { "source": "endpoint", "source_slug": "my-api", "amount": 0.01, "currency": "USDC", "tx_hash": "0x...", "payer_wallet": "0x...", "network": "base", "status": "confirmed" } }

Credits note: when endpoint credits = 0, no requests go through, so no payments happen and no webhook events fire.

Backward compatible: all existing endpoints unaffected (webhook_url defaults to null, events fire only when webhook_url is set).

v1.1.3 | 2026-02-24T19:42:16.752Z | user

x402-layer 1.1.3

• Updated pricing for endpoint creation: now $1 (was $5), includes 4,000 starting credits (was 20,000).
• Updated documentation to reflect new credit and pricing model.
• Scripts and instructions now show pricing/credit adjustments.

v1.1.2 | 2026-02-15T08:11:11.918Z | auto

x402-layer 1.1.2

• Updated documentation in SKILL.md with minor clarifications.
• Scripts updated: awal_bridge.py, consume_product.py, wallet_signing.py (details not specified).
• Internal maintenance and small improvements.

v1.1.1 | 2026-02-14T19:26:08.959Z | user

[1.1.1] - 2026-02-15

Bug Fixes:

• Fixed AWAL CLI command: Updated from "pay" to "x402 pay"
• Fixed AWAL URL handling: Pass full URL instead of split format
• Fixed endpoint creation for AWAL: Backend now includes EIP-712 domain parameters

Changes:

• scripts/awal_bridge.py - Updated CLI command and URL handling
• Backend - Added EIP-712 domain params for AWAL compatibility

Tested:

• AWAL endpoint creation verified working
• PK mode unchanged and functional

v1.1.0 | 2026-02-14T11:53:18.272Z | user

x402-layer v1.1.0 Release Notes Release Date: February 14, 2026

---

RELEASE SUMMARY

Coinbase Agentic Wallet (AWAL) Integration - AI agents can now make Base network payments without exposing private keys.

---

NEW FEATURES

Coinbase Agentic Wallet (AWAL) Support:

• Full AWAL integration for all Base network payments
• No private key exposure required when using AWAL mode
• Automatic authentication mode detection (AWAL vs private-key)
• Seamless fallback to private-key mode when AWAL is not configured

Environment Variables Added:

• X402_USE_AWAL: Set "1" to enable Coinbase Agentic Wallet for Base
• X402_AUTH_MODE: Auth selection - auto, private-key, or awal
• X402_PREFER_NETWORK: Network selection - base or solana
• AWAL_PACKAGE: NPM package/version for AWAL CLI (default: [email protected])
• AWAL_BIN: Preinstalled awal binary path
• AWAL_FORCE_NPX: Set "1" to force npx even when binary exists

---

SCRIPTS UPDATED

• pay_base.py: AWAL payment support
• create_endpoint.py: AWAL support for $5 endpoint creation fee
• topup_endpoint.py: AWAL support for endpoint credit recharging
• recharge_credits.py: AWAL support for credit pack purchases
• consume_product.py: AWAL support for digital product consumption

---

SKILL.MD UPDATES

• Added AWAL to skill description for discovery
• Added all environment variables to metadata frontmatter
• Added "Option B: Coinbase Agentic Wallet (AWAL)" setup section
• Added "Security Notice" section with best practices
• Updated environment reference table

---

AWAL DEPENDENCY (Optional)

AWAL is optional. To use AWAL mode, users should first install the Coinbase skill:

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

---

BACKWARD COMPATIBILITY

• Private-key mode works exactly as before
• Solana payments unchanged (private-key only)
• All existing environment variables (PRIVATE_KEY, WALLET_ADDRESS, SOLANA_SECRET_KEY) still work
• No breaking changes

---

NETWORK SUPPORT

Base: AWAL Supported, Private Key Supported Solana: AWAL Not supported, Private Key Required

Note: AWAL is a Coinbase CDP product and only supports EVM chains (Base, Ethereum). Solana payments continue to use private-key mode.

---

SECURITY NOTICE

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
• Use AWAL for production: Eliminates private key exposure entirely for Base payments

---

TESTING PERFORMED

• Base payments via private key: Passed
• Base payments via AWAL: Passed
• Solana payments via private key: Passed
• Endpoint creation ($5 fee): Passed
• Credit purchases: Passed
• Marketplace operations: Passed

---

UPGRADE INSTRUCTIONS (From v1.0.0 to v1.1.0)

1. No action required for existing users - everything works as before

2. To use AWAL (optional):

   npx skills add coinbase/agentic-wallet-skills npx awal auth login [email protected] export X402_USE_AWAL=1 python scripts/pay_base.py https://api.x402layer.cc/e/endpoint

---

Skill Slug: x402-layer Version: 1.1.0 Previous Version: 1.0.0

v1.0.1 | 2026-02-02T11:33:13.875Z | user

x402-layer 1.0.1

• Version bump (1.0.0 → 1.0.1).
• Security: Added strict x-api-key verification for marketplace listing/unlisting.
• Docs: Updated README.md with critical API Key security note.
• Script: Updated list_on_marketplace.py to support X_API_KEY env var.

v1.0.0 | 2026-02-02T10:49:56.579Z | user

v1.0.0 - Initial Release

🎉 Features

Consumer Mode

• Pay-Per-Request on Base (100% reliable) and Solana (EIP-712/versioned txs)
• Credit System for zero-latency API access
• Marketplace Discovery: browse, search, filter by category
• Digital Products: purchase and download files

Provider Mode

• Endpoint Creation: $5 one-time (includes 20,000 credits)
• Marketplace Listing during creation OR update afterward
• List/Unlist endpoint visibility control
• Credit Top-up to keep services running

Security

• API key verification (x-api-key header)
• EIP-712 typed data signatures (Base)
• Versioned transactions with fee payer (Solana)

Scripts (11)

pay_base, pay_solana, consume_credits, check_credits, recharge_credits, consume_product, discover_marketplace, create_endpoint, manage_endpoint, topup_endpoint, list_on_marketplace

Known Issues

• Solana ~75% success rate (retry logic included)

Archive index:

Archive v1.2.1: 26 files, 42328 bytes

Files: references/agentic-endpoints.md (523b), references/credit-based.md (1561b), references/marketplace.md (1001b), references/pay-per-request.md (4833b), references/payment-signing.md (1864b), requirements.txt (368b), scripts/awal_bridge.py (4378b), scripts/awal_cli.py (4063b), scripts/check_credits.py (1709b), scripts/consume_credits.py (2345b), scripts/consume_product.py (10724b), scripts/create_endpoint.py (9191b), scripts/discover_marketplace.py (3262b), scripts/list_on_marketplace.py (5596b), scripts/manage_endpoint.py (7122b), scripts/manage_webhook.py (4360b), scripts/network_selection.py (2280b), scripts/pay_base.py (2668b), scripts/pay_solana.py (2843b), scripts/recharge_credits.py (4854b), scripts/solana_signing.py (7103b), scripts/topup_endpoint.py (4024b), scripts/wallet_signing.py (5808b), SETUP_AWAL.md (1364b), SKILL.md (14760b), _meta.json (129b)

File v1.2.1:SKILL.md

---

name: x402-layer version: 1.2.1 description: | This 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 credits", "list endpoint on marketplace", "buy API credits", "topup endpoint", "browse x402 marketplace", "set up webhook", "receive payment notifications", "manage endpoint webhook", use "Coinbase Agentic Wallet (AWAL)", or manage x402 Singularity Layer operations on Base or Solana networks. homepage: https://studio.x402layer.cc/docs/agentic-access/openclaw-skill metadata: clawdbot: emoji: "⚡" homepage: https://studio.x402layer.cc os: - linux - darwin requires: bins: - python3 env: # Core credentials (required for payments) - WALLET_ADDRESS - PRIVATE_KEY # Solana payments (required for Solana network) - SOLANA_SECRET_KEY # Provider operations (required for endpoint management) - X_API_KEY - API_KEY # AWAL mode (optional - for Coinbase Agentic Wallet) - X402_USE_AWAL - X402_AUTH_MODE - X402_PREFER_NETWORK - AWAL_PACKAGE - AWAL_BIN - AWAL_FORCE_NPX allowed-tools:

• Read
• Write
• Edit
• Bash
• WebFetch

---

x402 Singularity Layer

x402 is a Web3 payment layer enabling AI agents to:

• 💰 Pay for API access using USDC
• 🚀 Deploy monetized endpoints
• 🔍 Discover services via marketplace
• 📊 Manage endpoints and credits
• 🔔 Webhooks — receive payment notifications

Networks: Base (EVM) • Solana
Currency: USDC
Protocol: HTTP 402 Payment Required

---

Quick Start

1. Install Dependencies

pip install -r {baseDir}/requirements.txt

2. Set Up Wallet (Choose One Mode)

Option A: Private Keys (existing mode)

# For Base (EVM)
export PRIVATE_KEY="0x..."
export WALLET_ADDRESS="0x..."

# For Solana (optional)
export SOLANA_SECRET_KEY="[1,2,3,...]"  # JSON array

Option B: Coinbase Agentic Wallet (AWAL)

For 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=1

Note: 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.

---

⚠️ Security Notice

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

---

Scripts Overview

🛒 CONSUMER MODE (Buying Services)

| 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 |

🏭 PROVIDER MODE (Selling 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 |

---

Security: API Key Verification

[!IMPORTANT] When you create an endpoint, x402 acts as a proxy to your origin server. You MUST verify that 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).

---

Credit System: How It Works

[!WARNING] Credits are NOT test credits! They are consumed with every API request.

Flow

User pays $0.01 → Your wallet receives payment → 1 credit deducted from your endpoint

Economics

| 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 |

Example

1. Create endpoint: Pay $1, get 4,000 credits
2. Set price: $0.01 per call
3. User calls your API 1,000 times: You earn $10, 1,000 credits deducted
4. Remaining: 19,000 credits + $10 profit
5. Credits run low? Recharge with topup_endpoint.py

What Happens When Credits = 0?

Your endpoint stops working and returns an error. Users cannot access it until you recharge.

---

Consumer Flows

A. Pay-Per-Request (Recommended)

# 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-data

B. Credit-Based Access (Fastest)

Pre-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

C. Discover Services

# 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 list

---

Provider Flows

A. Create Endpoint ($1 one-time)

Deploy 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-list

With 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.jpg

Available 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.

B. Manage Your Endpoint

# 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.02

C. Recharge Your Endpoint (Required to Keep It Working)

Your 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.

D. Marketplace Listing Management

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.jpg

Option 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 --unlist

Tip: Use list_on_marketplace.py to update your listing anytime - change category, description, or images without recreating the endpoint.

E. Webhooks (Payment Notifications)

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/webhook

Add or update webhook on existing endpoint:

python {baseDir}/scripts/manage_webhook.py set my-api https://my-server.com/webhook

Check webhook status:

python {baseDir}/scripts/manage_webhook.py info my-api

Remove 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.

Webhook Event Types

| 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"
  }
}

Verify Webhook Signature

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.

---

Payment Technical Details

Base (EVM) - EIP-712 Signatures

Uses USDC TransferWithAuthorization (EIP-3009):

• Gasless for payer
• Facilitator settles on-chain
• 100% reliable

Solana - Versioned Transactions

Uses VersionedTransaction with MessageV0:

• Facilitator pays gas (from extra.feePayer)
• SPL Token TransferChecked instruction
• ~75% success rate (retry logic included)

---

Environment Reference

| 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: [email protected]) | | 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 |

---

API Base URL

• Endpoints: https://api.x402layer.cc/e/{slug}
• Marketplace: https://api.x402layer.cc/api/marketplace
• Credits: https://api.x402layer.cc/api/credits/*
• Agent API: https://api.x402layer.cc/agent/*

---

Resources

• 📖 Documentation: studio.x402layer.cc/docs/agentic-access/openclaw-skill
• 💻 GitHub Docs: github.com/ivaavimusic/SGL_DOCS_2025
• 🐦 OpenClaw: x.com/openclaw
• 🌐 x402 Studio: studio.x402layer.cc

---

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.

File v1.2.1:_meta.json

{ "ownerId": "kn73xndw522wt8y06avyd39a8h7ztbeh", "slug": "x402-layer", "version": "1.2.1", "publishedAt": 1772198367315 }

File v1.2.1:references/agentic-endpoints.md

Agentic Endpoint Creation

Deploy your own monetized API endpoints programmatically.

Endpoint

POST https://api.x402layer.cc/agent/endpoints

Pricing

Create: $1 (4,000 credits included) Top-up: $1 = 500 credits

Create Flow

1. POST with endpoint config (name, slug, origin_url, chain)
2. Get 402 challenge
3. Sign with EIP-712
4. Send X-Payment header
5. Receive gateway URL and API key

Top-Up

PUT /agent/endpoints/<slug> with topup_amount

Check Status

GET /agent/endpoints/<slug> with x-api-key header

File v1.2.1:references/credit-based.md

Credit-Based Access

For high-frequency or latency-sensitive API calls. Pre-purchase credits, consume instantly.

Why Use Credits?

• Zero latency (no blockchain wait)
• Zero gas fees per request
• Simple header-based access

Usage

Check Balance

curl "https://api.x402layer.cc/api/credits/balance?endpoint=<slug>" \
  -H "x-wallet-address: 0xYourWallet..."

Consume Endpoint

curl "https://api.x402layer.cc/e/<slug>" \
  -H "x-wallet-address: 0xYourWallet..." \
  -H "Content-Type: application/json" \
  -d "{\"prompt\": \"your request\"}"

Insufficient Credits Response

When out of credits, you get a 402 with purchase options:

{
  "error": "Insufficient credits",
  "current_balance": 0,
  "purchase_url": "https://studio.x402layer.cc/pay/credits/<slug>",
  "credit_package": {"size": 69, "price": 0.01},
  "accepts": [...]
}

Purchasing Credits

Use the standard 402 flow on the purchase_url:

1. GET the purchase URL
2. Parse 402 challenge
3. Sign EIP-712 payment
4. Send with X-Payment header
5. Credits added to wallet

Example Python

import requests

def call_with_credits(url, wallet, data):
    resp = requests.post(url, 
        json=data,
        headers={"x-wallet-address": wallet})
    
    if resp.status_code == 402:
        print("Need credits!", resp.json()["purchase_url"])
        return None
    
    return resp.json()

Scripts

• check_credits.py - Query balance
• consume_with_credits.py - Use credits
• recharge_credits.py - Top up via payment

File v1.2.1:references/marketplace.md

Marketplace Discovery

Browse, search, and consume x402 marketplace services.

Endpoints

| Endpoint | Method | Description | |----------|--------|-------------| | /api/marketplace | GET | List all public listings | | /api/marketplace/search?q=<term> | GET | Search by keyword | | /api/marketplace/featured | GET | Featured listings | | /api/marketplace/<slug> | GET | Single endpoint details | | /api/marketplace/list | POST | List endpoint (provider) | | /api/marketplace/unlist | POST | Remove from marketplace |

Categories

ai, data, finance, utility, social, gaming

Example: Browse All

python discover_marketplace.py

Example: Consume Found Service

# Get details for an endpoint
python discover_marketplace.py details weather-api

# Pay and consume
python pay_base.py https://api.x402layer.cc/e/weather-api

Scripts

• discover_marketplace.py - Browse/search marketplace
• list_on_marketplace.py - List/unlist your endpoint

File v1.2.1:references/pay-per-request.md

Pay-Per-Request (Direct Mode)

Pay-Per-Request uses the HTTP 402 Payment Required status code to negotiate payment for each individual API call.

Critical: EIP-712 Signatures

x402 uses EIP-712 typed data signatures, NOT raw ERC20 transfers.

The facilitator validates and broadcasts the payment. You only need to sign a permit.

Coinbase Agentic Wallet (AWAL) Shortcut

If you do not want local private-key signing, use AWAL:

python {baseDir}/scripts/awal_cli.py run auth login [email protected]
python {baseDir}/scripts/awal_cli.py run auth verify <flow_id> <otp>
python {baseDir}/scripts/awal_cli.py pay-url https://api.x402layer.cc/e/my-endpoint

---

Interaction Cycle

1. Naïve Request

curl https://api.x402layer.cc/e/my-endpoint

2. Parse 402 Challenge

{
  "x402Version": 1,
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "maxAmountRequired": "10000",
      "payTo": "0xCD95802A4aBddD75A5750DD2d6935007eF268275",
      "asset": "eip155:8453/erc20:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "extra": {
        "name": "USD Coin",
        "version": "2"
      }
    },
    {
      "scheme": "exact",
      "network": "solana",
      "maxAmountRequired": "10000",
      "payTo": "3rcdSzTam4h5e6UN2USv5L2t9R4Ah466B4mHgxRVEqCx",
      "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "extra": {
        "feePayer": "BENrLoUbndxoNMUS5JXApGMtNykLjFXXixMtpDwDR9SP"
      }
    }
  ]
}

3. Sign Payment (EIP-712)

import os
import time
import json
import base64
from eth_account import Account
from eth_account.messages import encode_typed_data

def sign_x402_payment(challenge, wallet_address, private_key):
    """Sign x402 payment using EIP-712 (NOT raw ERC20 transfer)"""
    
    # Find Base option
    base_option = next((a for a in challenge["accepts"] if a["network"] == "base"), None)
    if not base_option:
        raise ValueError("No Base payment option")
    
    # Domain from extra field
    extra = base_option.get("extra", {})
    domain = {
        "name": extra.get("name", "USD Coin"),
        "version": extra.get("version", "2"),
        "chainId": 8453,
        "verifyingContract": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
    }
    
    # EIP-712 types for TransferWithAuthorization
    types = {
        "TransferWithAuthorization": [
            {"name": "from", "type": "address"},
            {"name": "to", "type": "address"},
            {"name": "value", "type": "uint256"},
            {"name": "validAfter", "type": "uint256"},
            {"name": "validBefore", "type": "uint256"},
            {"name": "nonce", "type": "bytes32"},
        ]
    }
    
    # Message data
    nonce = os.urandom(32)
    message = {
        "from": wallet_address,
        "to": base_option["payTo"],
        "value": int(base_option["maxAmountRequired"]),
        "validAfter": 0,
        "validBefore": int(time.time()) + 3600,
        "nonce": nonce,
    }
    
    # Sign
    encoded = encode_typed_data(domain, types, message)
    signed = Account.sign_message(encoded, private_key)
    
    # Build X-Payment payload
    payment_obj = {
        "x402Version": 1,
        "scheme": "exact",
        "network": "base",
        "payload": {
            "signature": signed.signature.hex(),
            "from": wallet_address,
            "to": base_option["payTo"],
            "value": str(message["value"]),
            "validAfter": str(message["validAfter"]),
            "validBefore": str(message["validBefore"]),
            "nonce": "0x" + nonce.hex(),
        }
    }
    
    return base64.b64encode(json.dumps(payment_obj).encode()).decode()

4. Authorized Request

import requests

x_payment = sign_x402_payment(challenge, wallet, key)
response = requests.get(url, headers={"X-Payment": x_payment})
print(response.json())

---

Free Endpoints (maxAmountRequired = "0")

Even if amount is 0, you MUST still send a signed payload. This authenticates the caller.

---

Solana Payments

Solana uses SPL Token transfers (not EIP-712). The transaction must include the feePayer from challenge.

from solders.keypair import Keypair
from solders.transaction import Transaction
from solders.pubkey import Pubkey
from spl.token.instructions import transfer_checked
import base64

# Build SPL transfer transaction
# Include feePayer from challenge extra
# Serialize and base64 encode

---

Common Errors

| Error | Cause | Fix | |-------|-------|-----| | "Invalid signature" | Using raw transfer() | Use EIP-712 signing | | "Nonce already used" | Replay attack | Generate fresh random nonce | | "validBefore expired" | Timeout | Set validBefore = now + 3600 | | "Wrong domain" | Bad name/version | Use "USD Coin" v2 for Base USDC |

File v1.2.1:references/payment-signing.md

Payment Signing Reference

Critical Understanding

x402 uses EIP-712 typed data signatures for TransferWithAuthorization. The facilitator verifies signatures and settles the payment.

Base (EVM) - EIP-712 Signing

Domain (Base USDC)

domain = {
    "name": "USD Coin",
    "version": "2",
    "chainId": 8453,
    "verifyingContract": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
}

Types

types = {
    "TransferWithAuthorization": [
        {"name": "from", "type": "address"},
        {"name": "to", "type": "address"},
        {"name": "value", "type": "uint256"},
        {"name": "validAfter", "type": "uint256"},
        {"name": "validBefore", "type": "uint256"},
        {"name": "nonce", "type": "bytes32"},
    ]
}

Signing

from eth_account import Account
from eth_account.messages import encode_typed_data
import os, time

message = {
    "from": wallet,
    "to": challenge["payTo"],
    "value": int(challenge["maxAmountRequired"]),
    "validAfter": 0,
    "validBefore": int(time.time()) + 3600,
    "nonce": os.urandom(32),
}

encoded = encode_typed_data(domain, types, message)
signed = Account.sign_message(encoded, private_key)

Solana - SPL Transfer

Solana uses SPL Token transfers with base64 encoding.

Coinbase Agentic Wallet (AWAL) Mode

You can avoid direct key management by using AWAL:

python {baseDir}/scripts/awal_cli.py run auth login [email protected]
python {baseDir}/scripts/awal_cli.py run auth verify <flow_id> <otp>
python {baseDir}/scripts/awal_cli.py pay-url https://api.x402layer.cc/e/weather-data

AWAL package version can be pinned:

export AWAL_PACKAGE="[email protected]"

X-Payment Header Format

Base64 encode the payment JSON:

import json, base64
x_payment = base64.b64encode(json.dumps(payload).encode()).decode()

File v1.2.1:SETUP_AWAL.md

Setup Guide: Coinbase Agentic Wallet (AWAL) CLI

To use the x402-layer skill with Coinbase Agentic Wallet (AWAL) for Base payments, you need to install the awal CLI tool.

Prerequisites

• Node.js (version 18+ recommended)
• NPM or Yarn

Option 1: Global Installation (Recommended)

Installing globally allows you to run awal commands directly from any directory.

npm install -g awal

Verify installation:

awal --version

Option 2: Using NPX (No Installation Required)

You can run commands without installing awal globally by prefixing with npx.

npx awal --version

Authentication

1. Login: Start the authentication process. You will receive an email with an OTP.

   # If installed globally:
   awal auth login [email protected]
   
   # If using npx:
   npx awal auth login [email protected]
   

2. Verify: Check your email for the OTP and complete the login.

   # Replace <flow-id> and <otp-code> with values from the login step and email.
   awal auth verify <flow-id> <otp-code>
   

3. Check Status: Confirm you are logged in.

   awal status
   

Configuration for x402-layer

Once setup, ensure you export the necessary environment variable to enable AWAL mode in the scripts:

export X402_USE_AWAL=1

File v1.2.1:requirements.txt

x402 Layer - Python Dependencies

Install: pip install -r requirements.txt

EVM/Base payments - Required for EIP-712 signing

eth-account>=0.10.0 web3>=6.0.0

HTTP requests

requests>=2.28.0

Environment variables

python-dotenv>=1.0.0

Solana payments - Optional, only needed for Solana network

Uncomment if using Solana:

solders>=0.20.0

solana>=0.30.0

Archive v1.2.0: 26 files, 42062 bytes

Files: references/agentic-endpoints.md (523b), references/credit-based.md (1561b), references/marketplace.md (1001b), references/pay-per-request.md (4833b), references/payment-signing.md (1864b), requirements.txt (368b), scripts/awal_bridge.py (4378b), scripts/awal_cli.py (4063b), scripts/check_credits.py (1709b), scripts/consume_credits.py (2345b), scripts/consume_product.py (10724b), scripts/create_endpoint.py (9191b), scripts/discover_marketplace.py (3262b), scripts/list_on_marketplace.py (5596b), scripts/manage_endpoint.py (7122b), scripts/manage_webhook.py (4360b), scripts/network_selection.py (2280b), scripts/pay_base.py (2668b), scripts/pay_solana.py (2843b), scripts/recharge_credits.py (4854b), scripts/solana_signing.py (7103b), scripts/topup_endpoint.py (4024b), scripts/wallet_signing.py (5808b), SETUP_AWAL.md (1364b), SKILL.md (13800b), _meta.json (129b)

File v1.2.0:SKILL.md

---

name: x402-layer version: 1.2.0 description: | This 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 credits", "list endpoint on marketplace", "buy API credits", "topup endpoint", "browse x402 marketplace", "set up webhook", "receive payment notifications", "manage endpoint webhook", use "Coinbase Agentic Wallet (AWAL)", or manage x402 Singularity Layer operations on Base or Solana networks. homepage: https://studio.x402layer.cc/docs/agentic-access/openclaw-skill metadata: clawdbot: emoji: "⚡" homepage: https://studio.x402layer.cc os: - linux - darwin requires: bins: - python3 env: # Core credentials (required for payments) - WALLET_ADDRESS - PRIVATE_KEY # Solana payments (required for Solana network) - SOLANA_SECRET_KEY # Provider operations (required for endpoint management) - X_API_KEY - API_KEY # AWAL mode (optional - for Coinbase Agentic Wallet) - X402_USE_AWAL - X402_AUTH_MODE - X402_PREFER_NETWORK - AWAL_PACKAGE - AWAL_BIN - AWAL_FORCE_NPX allowed-tools:

• Read
• Write
• Edit
• Bash
• WebFetch

---

x402 Singularity Layer

x402 is a Web3 payment layer enabling AI agents to:

• 💰 Pay for API access using USDC
• 🚀 Deploy monetized endpoints
• 🔍 Discover services via marketplace
• 📊 Manage endpoints and credits
• 🔔 Webhooks — receive payment notifications

Networks: Base (EVM) • Solana
Currency: USDC
Protocol: HTTP 402 Payment Required

---

Quick Start

1. Install Dependencies

pip install -r {baseDir}/requirements.txt

2. Set Up Wallet (Choose One Mode)

Option A: Private Keys (existing mode)

# For Base (EVM)
export PRIVATE_KEY="0x..."
export WALLET_ADDRESS="0x..."

# For Solana (optional)
export SOLANA_SECRET_KEY="[1,2,3,...]"  # JSON array

Option B: Coinbase Agentic Wallet (AWAL)

For 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=1

Note: 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.

---

⚠️ Security Notice

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

---

Scripts Overview

🛒 CONSUMER MODE (Buying Services)

| 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 |

🏭 PROVIDER MODE (Selling 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 |

---

Security: API Key Verification

[!IMPORTANT] When you create an endpoint, x402 acts as a proxy to your origin server. You MUST verify that 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).

---

Credit System: How It Works

[!WARNING] Credits are NOT test credits! They are consumed with every API request.

Flow

User pays $0.01 → Your wallet receives payment → 1 credit deducted from your endpoint

Economics

| 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 |

Example

1. Create endpoint: Pay $1, get 4,000 credits
2. Set price: $0.01 per call
3. User calls your API 1,000 times: You earn $10, 1,000 credits deducted
4. Remaining: 19,000 credits + $10 profit
5. Credits run low? Recharge with topup_endpoint.py

What Happens When Credits = 0?

Your endpoint stops working and returns an error. Users cannot access it until you recharge.

---

Consumer Flows

A. Pay-Per-Request (Recommended)

# 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-data

B. Credit-Based Access (Fastest)

Pre-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

C. Discover Services

# 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 list

---

Provider Flows

A. Create Endpoint ($1 one-time)

Deploy 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-list

With 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.jpg

Available 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.

B. Manage Your Endpoint

# 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.02

C. Recharge Your Endpoint (Required to Keep It Working)

Your 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.

D. Marketplace Listing Management

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.jpg

Option 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 --unlist

Tip: Use list_on_marketplace.py to update your listing anytime - change category, description, or images without recreating the endpoint.

E. Webhooks (Payment Notifications)

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/webhook

Add or update webhook on existing endpoint:

python {baseDir}/scripts/manage_webhook.py set my-api https://my-server.com/webhook

Check webhook status:

python {baseDir}/scripts/manage_webhook.py info my-api

Remove 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.

Webhook Event Format

Your endpoint receives POST requests with:

Content-Type: application/json
X-X402-Event: payment.succeeded
X-X402-Signature: t=<timestamp>,v1=<hmac_sha256>

{
  "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"
  }
}

Verify Webhook Signature

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.

---

Payment Technical Details

Base (EVM) - EIP-712 Signatures

Uses USDC TransferWithAuthorization (EIP-3009):

• Gasless for payer
• Facilitator settles on-chain
• 100% reliable

Solana - Versioned Transactions

Uses VersionedTransaction with MessageV0:

• Facilitator pays gas (from extra.feePayer)
• SPL Token TransferChecked instruction
• ~75% success rate (retry logic included)

---

Environment Reference

| 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: [email protected]) | | 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 |

---

API Base URL

• Endpoints: https://api.x402layer.cc/e/{slug}
• Marketplace: https://api.x402layer.cc/api/marketplace
• Credits: https://api.x402layer.cc/api/credits/*
• Agent API: https://api.x402layer.cc/agent/*

---

Resources

• 📖 Documentation: studio.x402layer.cc/docs/agentic-access/openclaw-skill
• 💻 GitHub Docs: github.com/ivaavimusic/SGL_DOCS_2025
• 🐦 OpenClaw: x.com/openclaw
• 🌐 x402 Studio: studio.x402layer.cc

---

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.

File v1.2.0:_meta.json

{ "ownerId": "kn73xndw522wt8y06avyd39a8h7ztbeh", "slug": "x402-layer", "version": "1.2.0", "publishedAt": 1772182986877 }

File v1.2.0:references/agentic-endpoints.md

Agentic Endpoint Creation

Deploy your own monetized API endpoints programmatically.

Endpoint

POST https://api.x402layer.cc/agent/endpoints

Pricing

Create: $1 (4,000 credits included) Top-up: $1 = 500 credits

Create Flow

1. POST with endpoint config (name, slug, origin_url, chain)
2. Get 402 challenge
3. Sign with EIP-712
4. Send X-Payment header
5. Receive gateway URL and API key

Top-Up

PUT /agent/endpoints/<slug> with topup_amount

Check Status

GET /agent/endpoints/<slug> with x-api-key header

File v1.2.0:references/credit-based.md

Credit-Based Access

For high-frequency or latency-sensitive API calls. Pre-purchase credits, consume instantly.

Why Use Credits?

• Zero latency (no blockchain wait)
• Zero gas fees per request
• Simple header-based access

Usage

Check Balance

curl "https://api.x402layer.cc/api/credits/balance?endpoint=<slug>" \
  -H "x-wallet-address: 0xYourWallet..."

Consume Endpoint

curl "https://api.x402layer.cc/e/<slug>" \
  -H "x-wallet-address: 0xYourWallet..." \
  -H "Content-Type: application/json" \
  -d "{\"prompt\": \"your request\"}"

Insufficient Credits Response

When out of credits, you get a 402 with purchase options:

{
  "error": "Insufficient credits",
  "current_balance": 0,
  "purchase_url": "https://studio.x402layer.cc/pay/credits/<slug>",
  "credit_package": {"size": 69, "price": 0.01},
  "accepts": [...]
}

Purchasing Credits

Use the standard 402 flow on the purchase_url:

1. GET the purchase URL
2. Parse 402 challenge
3. Sign EIP-712 payment
4. Send with X-Payment header
5. Credits added to wallet

Example Python

import requests

def call_with_credits(url, wallet, data):
    resp = requests.post(url, 
        json=data,
        headers={"x-wallet-address": wallet})
    
    if resp.status_code == 402:
        print("Need credits!", resp.json()["purchase_url"])
        return None
    
    return resp.json()

Scripts

• check_credits.py - Query balance
• consume_with_credits.py - Use credits
• recharge_credits.py - Top up via payment

File v1.2.0:references/marketplace.md

Marketplace Discovery

Browse, search, and consume x402 marketplace services.

Endpoints

| Endpoint | Method | Description | |----------|--------|-------------| | /api/marketplace | GET | List all public listings | | /api/marketplace/search?q=<term> | GET | Search by keyword | | /api/marketplace/featured | GET | Featured listings | | /api/marketplace/<slug> | GET | Single endpoint details | | /api/marketplace/list | POST | List endpoint (provider) | | /api/marketplace/unlist | POST | Remove from marketplace |

Categories

ai, data, finance, utility, social, gaming

Example: Browse All

python discover_marketplace.py

Example: Consume Found Service

# Get details for an endpoint
python discover_marketplace.py details weather-api

# Pay and consume
python pay_base.py https://api.x402layer.cc/e/weather-api

Scripts

• discover_marketplace.py - Browse/search marketplace
• list_on_marketplace.py - List/unlist your endpoint

File v1.2.0:references/pay-per-request.md

Pay-Per-Request (Direct Mode)

Pay-Per-Request uses the HTTP 402 Payment Required status code to negotiate payment for each individual API call.

Critical: EIP-712 Signatures

x402 uses EIP-712 typed data signatures, NOT raw ERC20 transfers.

The facilitator validates and broadcasts the payment. You only need to sign a permit.

Coinbase Agentic Wallet (AWAL) Shortcut

If you do not want local private-key signing, use AWAL:

python {baseDir}/scripts/awal_cli.py run auth login [email protected]
python {baseDir}/scripts/awal_cli.py run auth verify <flow_id> <otp>
python {baseDir}/scripts/awal_cli.py pay-url https://api.x402layer.cc/e/my-endpoint

---

Interaction Cycle

1. Naïve Request

curl https://api.x402layer.cc/e/my-endpoint

2. Parse 402 Challenge

{
  "x402Version": 1,
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "maxAmountRequired": "10000",
      "payTo": "0xCD95802A4aBddD75A5750DD2d6935007eF268275",
      "asset": "eip155:8453/erc20:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "extra": {
        "name": "USD Coin",
        "version": "2"
      }
    },
    {
      "scheme": "exact",
      "network": "solana",
      "maxAmountRequired": "10000",
      "payTo": "3rcdSzTam4h5e6UN2USv5L2t9R4Ah466B4mHgxRVEqCx",
      "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "extra": {
        "feePayer": "BENrLoUbndxoNMUS5JXApGMtNykLjFXXixMtpDwDR9SP"
      }
    }
  ]
}

3. Sign Payment (EIP-712)

import os
import time
import json
import base64
from eth_account import Account
from eth_account.messages import encode_typed_data

def sign_x402_payment(challenge, wallet_address, private_key):
    """Sign x402 payment using EIP-712 (NOT raw ERC20 transfer)"""
    
    # Find Base option
    base_option = next((a for a in challenge["accepts"] if a["network"] == "base"), None)
    if not base_option:
        raise ValueError("No Base payment option")
    
    # Domain from extra field
    extra = base_option.get("extra", {})
    domain = {
        "name": extra.get("name", "USD Coin"),
        "version": extra.get("version", "2"),
        "chainId": 8453,
        "verifyingContract": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
    }
    
    # EIP-712 types for TransferWithAuthorization
    types = {
        "TransferWithAuthorization": [
            {"name": "from", "type": "address"},
            {"name": "to", "type": "address"},
            {"name": "value", "type": "uint256"},
            {"name": "validAfter", "type": "uint256"},
            {"name": "validBefore", "type": "uint256"},
            {"name": "nonce", "type": "bytes32"},
        ]
    }
    
    # Message data
    nonce = os.urandom(32)
    message = {
        "from": wallet_address,
        "to": base_option["payTo"],
        "value": int(base_option["maxAmountRequired"]),
        "validAfter": 0,
        "validBefore": int(time.time()) + 3600,
        "nonce": nonce,
    }
    
    # Sign
    encoded = encode_typed_data(domain, types, message)
    signed = Account.sign_message(encoded, private_key)
    
    # Build X-Payment payload
    payment_obj = {
        "x402Version": 1,
        "scheme": "exact",
        "network": "base",
        "payload": {
            "signature": signed.signature.hex(),
            "from": wallet_address,
            "to": base_option["payTo"],
            "value": str(message["value"]),
            "validAfter": str(message["validAfter"]),
            "validBefore": str(message["validBefore"]),
            "nonce": "0x" + nonce.hex(),
        }
    }
    
    return base64.b64encode(json.dumps(payment_obj).encode()).decode()

4. Authorized Request

import requests

x_payment = sign_x402_payment(challenge, wallet, key)
response = requests.get(url, headers={"X-Payment": x_payment})
print(response.json())

---

Free Endpoints (maxAmountRequired = "0")

Even if amount is 0, you MUST still send a signed payload. This authenticates the caller.

---

Solana Payments

Solana uses SPL Token transfers (not EIP-712). The transaction must include the feePayer from challenge.

from solders.keypair import Keypair
from solders.transaction import Transaction
from solders.pubkey import Pubkey
from spl.token.instructions import transfer_checked
import base64

# Build SPL transfer transaction
# Include feePayer from challenge extra
# Serialize and base64 encode

---

Common Errors

| Error | Cause | Fix | |-------|-------|-----| | "Invalid signature" | Using raw transfer() | Use EIP-712 signing | | "Nonce already used" | Replay attack | Generate fresh random nonce | | "validBefore expired" | Timeout | Set validBefore = now + 3600 | | "Wrong domain" | Bad name/version | Use "USD Coin" v2 for Base USDC |

File v1.2.0:references/payment-signing.md

Payment Signing Reference

Critical Understanding

x402 uses EIP-712 typed data signatures for TransferWithAuthorization. The facilitator verifies signatures and settles the payment.

Base (EVM) - EIP-712 Signing

Domain (Base USDC)

domain = {
    "name": "USD Coin",
    "version": "2",
    "chainId": 8453,
    "verifyingContract": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
}

Types

types = {
    "TransferWithAuthorization": [
        {"name": "from", "type": "address"},
        {"name": "to", "type": "address"},
        {"name": "value", "type": "uint256"},
        {"name": "validAfter", "type": "uint256"},
        {"name": "validBefore", "type": "uint256"},
        {"name": "nonce", "type": "bytes32"},
    ]
}

Signing

from eth_account import Account
from eth_account.messages import encode_typed_data
import os, time

message = {
    "from": wallet,
    "to": challenge["payTo"],
    "value": int(challenge["maxAmountRequired"]),
    "validAfter": 0,
    "validBefore": int(time.time()) + 3600,
    "nonce": os.urandom(32),
}

encoded = encode_typed_data(domain, types, message)
signed = Account.sign_message(encoded, private_key)

Solana - SPL Transfer

Solana uses SPL Token transfers with base64 encoding.

Coinbase Agentic Wallet (AWAL) Mode

You can avoid direct key management by using AWAL:

python {baseDir}/scripts/awal_cli.py run auth login [email protected]
python {baseDir}/scripts/awal_cli.py run auth verify <flow_id> <otp>
python {baseDir}/scripts/awal_cli.py pay-url https://api.x402layer.cc/e/weather-data

AWAL package version can be pinned:

export AWAL_PACKAGE="[email protected]"

X-Payment Header Format

Base64 encode the payment JSON:

import json, base64
x_payment = base64.b64encode(json.dumps(payload).encode()).decode()

File v1.2.0:SETUP_AWAL.md

Setup Guide: Coinbase Agentic Wallet (AWAL) CLI

To use the x402-layer skill with Coinbase Agentic Wallet (AWAL) for Base payments, you need to install the awal CLI tool.

Prerequisites

• Node.js (version 18+ recommended)
• NPM or Yarn

Option 1: Global Installation (Recommended)

Installing globally allows you to run awal commands directly from any directory.

npm install -g awal

Verify installation:

awal --version

Option 2: Using NPX (No Installation Required)

You can run commands without installing awal globally by prefixing with npx.

npx awal --version

Authentication

1. Login: Start the authentication process. You will receive an email with an OTP.

   # If installed globally:
   awal auth login [email protected]
   
   # If using npx:
   npx awal auth login [email protected]
   

2. Verify: Check your email for the OTP and complete the login.

   # Replace <flow-id> and <otp-code> with values from the login step and email.
   awal auth verify <flow-id> <otp-code>
   

3. Check Status: Confirm you are logged in.

   awal status
   

Configuration for x402-layer

Once setup, ensure you export the necessary environment variable to enable AWAL mode in the scripts:

export X402_USE_AWAL=1

File v1.2.0:requirements.txt

x402 Layer - Python Dependencies

Install: pip install -r requirements.txt

EVM/Base payments - Required for EIP-712 signing

eth-account>=0.10.0 web3>=6.0.0

HTTP requests

requests>=2.28.0

Environment variables

python-dotenv>=1.0.0

Solana payments - Optional, only needed for Solana network

Uncomment if using Solana:

solders>=0.20.0

solana>=0.30.0