x402 Singularity Layer

Intent Router

Use this routing first, then load the relevant reference doc.

Quick Start

1) Install Skill Dependencies

pip install -r {baseDir}/requirements.txt

2) Choose Wallet Mode

Option A: private keys

export PRIVATE_KEY="0x..."
export WALLET_ADDRESS="0x..."
# Solana optional
export SOLANA_SECRET_KEY="base58-or-[1,2,3,...]"

Option B: Coinbase AWAL

# Install Coinbase AWAL skill (shortcut)
npx skills add coinbase/agentic-wallet-skills
export X402_USE_AWAL=1

Option C: OpenWallet / OWS

npm install -g @open-wallet-standard/core
export OWS_WALLET="hackathon-wallet"

Use private-key mode for deep ERC-8004 registration and any on-chain update path that still needs direct transaction signing. AWAL remains useful for x402 payment flows. OWS is optional-first for pay/discover/sign-message flows plus wallet-auth list/support flows through ows_cli.py and the shared wallet helpers. Do not export every credential shown above at once. Pick one wallet path and only the extra control-plane credentials the selected runbook needs.

3) Optional Dashboard / MCP Mode

If the user provides a dashboard PAT, the agent can also use Singularity MCP for owner-scoped account actions:

export SINGULARITY_PAT="sgl_pat_..."

Use MCP when the task is about:

• listing all endpoints or products owned by the dashboard user
• updating endpoint or product settings
• setting or removing webhooks
• requesting endpoint creation or top-up payment challenges in an owner-scoped way

Keep the direct scripts for:

• actual request payments and local signing
• AWAL-driven pay/discover flows
• OWS-driven pay/discover/sign-message flows
• support and XMTP flows
• wallet-first ERC-8004 / Solana-8004 registration and updates

Security note: scripts read only explicit process environment variables. .env files are not auto-loaded. Least-privilege note: the skill supports multiple credential types, but no single runbook needs all of them. Read-only discovery needs no secrets. PAT, API-key, AWAL, OWS, EVM, and Solana signing flows should be treated as separate capability paths, and users should set only the smallest subset required for the task in front of them. Risk note: this skill can sign messages, submit transactions, and call x402/studio APIs. Prefer AWAL, OWS, PATs, endpoint API keys, or throwaway wallets over long-lived private keys when possible.

Script Inventory

Consumer

Provider

Agent Registry + Reputation

Core Security Requirements

API Key Verification at Origin (mandatory)

When x402 proxies traffic to your origin, verify:

x-api-key: <YOUR_API_KEY>

Reject requests when missing/invalid.

Credit Economics (provider side)

• Endpoint creation: $1 one-time
• Starting credits: 4,000
• Top-up rate: 500 credits per $1
• Consumption: 1 credit per request
• If credits hit 0, endpoint stops serving until recharged

Fast Runbooks

A) Integrate Payments Into Your App

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

# 2. Add server-side fulfillment
python {baseDir}/scripts/manage_webhook.py set my-api https://my-server.com/webhook

# 3. Verify webhook signatures and payment receipts server-side
python {baseDir}/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

B) Pay and Consume

python {baseDir}/scripts/pay_base.py https://api.x402layer.cc/e/weather-data
python {baseDir}/scripts/pay_base.py https://api.x402layer.cc/e/weather-data --agentkit auto
python {baseDir}/scripts/pay_solana.py https://api.x402layer.cc/e/weather-data
python {baseDir}/scripts/consume_credits.py https://api.x402layer.cc/e/weather-data

# Optional OWS backend
python {baseDir}/scripts/ows_cli.py pay-url https://api.x402layer.cc/e/weather-data --wallet hackathon-wallet

C) Discover/Search Marketplace

python {baseDir}/scripts/discover_marketplace.py
python {baseDir}/scripts/discover_marketplace.py search weather
python {baseDir}/scripts/discover_marketplace.py details weather-api

# Optional OWS discovery path
python {baseDir}/scripts/ows_cli.py discover weather

D) Create and Manage Endpoint

python {baseDir}/scripts/create_endpoint.py my-api "My API" https://api.example.com 0.01
python {baseDir}/scripts/manage_endpoint.py list
python {baseDir}/scripts/manage_endpoint.py update my-api --price 0.02
python {baseDir}/scripts/topup_endpoint.py my-api 10

E) List/Update in Marketplace

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

F) Webhook Setup and Genuineness Verification

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

Studio seller webhooks are HMAC-signed. Expect:

• X-X402-Signature
• X-X402-Timestamp
• X-X402-Event
• X-X402-Event-Id

Verify HMAC-SHA256(timestamp + "." + rawBody) with the webhook signing_secret. Keep legacy raw-secret header checks only as backward-compatibility fallback for older receivers.

Webhook verification helper:

python {baseDir}/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

G) World AgentKit Benefits

# Inspect whether a listing advertises a verified human-backed agent wallet benefit
python {baseDir}/scripts/discover_marketplace.py details weather-data

# Attempt Base payment with AgentKit if the endpoint advertises a benefit
python {baseDir}/scripts/pay_base.py https://api.x402layer.cc/e/weather-data --agentkit auto

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

H) XMTP Support Threads

# Authenticate the current wallet for support APIs
python {baseDir}/scripts/support_auth.py login

# Check whether support is available for a listing
python {baseDir}/scripts/support_threads.py eligibility endpoint weather-data

# Open or reuse the support thread
python {baseDir}/scripts/support_threads.py open endpoint weather-data

# Read and send XMTP messages for a support thread
node {baseDir}/scripts/xmtp_support.mjs messages <thread_id>
node {baseDir}/scripts/xmtp_support.mjs send <thread_id> "Need help with this endpoint"

H2) OpenWallet / OWS

# List local OWS wallets
python {baseDir}/scripts/ows_cli.py wallet-list

# Sign a message without exporting a raw private key
python {baseDir}/scripts/ows_cli.py sign-message --chain ethereum --wallet hackathon-wallet --message "hello"

# Create an OWS agent API key
python {baseDir}/scripts/ows_cli.py key-create --name codex-agent --wallet hackathon-wallet

OWS now works well for wallet lookup, challenge signing, marketplace discovery, support auth, and wallet-auth list flows. Deep ERC-8004 registration and on-chain agent update transactions still require direct signing keys.

I) MCP Owner-Scoped Control Plane

# Set a dashboard PAT only for owner-scoped control-plane actions
export SINGULARITY_PAT="sgl_pat_..."

# Then use Singularity MCP for owner inventory/config operations such as:
# - list_my_endpoints
# - update_endpoint
# - list_my_products
# - update_product
# - set_webhook
# - remove_webhook
# - request_endpoint_creation_payment

J) Agent Registration + Reputation

python {baseDir}/scripts/list_my_endpoints.py

python {baseDir}/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

python {baseDir}/scripts/list_agents.py --network baseSepolia

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

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

python {baseDir}/scripts/submit_feedback.py \
  --network base \
  --agent-id 123 \
  --rating 5 \
  --comment "High quality responses"

References

Load only what is needed for the user task:

• references/payments-integration.md: product-vs-endpoint-vs-credits decision guide plus webhook/receipt fulfillment patterns.
• references/pay-per-request.md: EIP-712/Solana payment flow and low-level signing details.
• references/credit-based.md: credit purchase + consumption behavior and examples.
• references/marketplace.md: search/list/unlist marketplace endpoints.
• references/agentkit-benefits.md: discover, qualify for, and pay with World AgentKit human-backed agent wallet benefits.
• references/agentic-endpoints.md: endpoint creation/top-up/status API behavior.
• references/webhooks-verification.md: webhook events, signature verification, and receipt cross-checks.
• references/agent-registry-reputation.md: ERC-8004/Solana-8004 registration, discovery, management, and feedback rules.
• references/xmtp-support.md: how support chat works in Studio, what needs human setup, and how agents should coordinate with users.
• references/mcp-control-plane.md: when to use Singularity MCP, what PAT scopes are needed, and which owner-scoped actions should prefer MCP over direct scripts.
• references/openwallet-ows.md: optional OpenWallet / OWS wallet backend guidance, install commands, and current scope.
• references/payment-signing.md: exact signing domains/types/header payload details.

Environment Reference

No single task needs every variable below. Use least privilege and set only what the current script requires.

Credential Path Rule

Choose the smallest path that fits the task:

1. No-secret discovery: marketplace browsing and public listing inspection
2. Endpoint API key: endpoint, listing, and webhook management
3. PAT / MCP: owner-scoped dashboard inventory and control-plane operations
4. AWAL / OWS: delegated wallet auth or pay/discover/sign-message flows
5. Direct private keys: deep wallet-first registration, on-chain updates, or flows that still require local transaction signing

Common

Optional MCP Control Plane

Provider and Marketplace Management

Solana

Support and XMTP

Agent Registry and Feedback

API Base Paths

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

Resources

• Docs: https://docs.x402layer.cc/agentic-access/openclaw-skill
• MCP docs: https://studio.x402layer.cc/docs/agentic-access/mcp-server
• SDK docs: https://studio.x402layer.cc/docs/developer/sdk-receipts
• GitHub docs repo: https://github.com/ivaavimusic/SGL_DOCS_2025
• x402 Studio: https://studio.x402layer.cc

Known Issue

Solana exact-payment flows must use the feePayer returned by the challenge and keep the transaction compute-unit limit within facilitator requirements. pay_solana.py and solana_signing.py handle this for the current PayAI-backed flow; prefer Base when you need the simplest production path.

OpenWallet / OWS support is optional-first in this release: use it for pay/discover/sign-message flows and wallet-auth list/support flows, but keep private-key mode for deep wallet-first registration and on-chain update transaction paths. OWS execution now requires a local ows binary (or OWS_BIN) instead of fetching code on demand via runtime npx.

Credential safety

This skill supports many optional workflows, so it can work with many credential types. That does not mean you should set all of them.

Preferred order of safety when possible:

1. Read-only discovery with no secrets
2. Endpoint API keys or PATs for scoped control-plane actions
3. AWAL or OWS for delegated/local wallet access
4. Dedicated throwaway private keys for direct signing

Do not export a long-lived high-value custody wallet into the environment just to browse, inspect, or test small flows.