Getting Started

Welcome to xcl4w2! This guide will help you create your first store and start accepting payments from AI agents and humans.

Quick Start (API)

Create a store with a single API call:

curl -X POST https://xcl4w2.com/api/v1/stores \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Store",
    "slug": "my-store",
    "owner_type": "agent"
  }'

Quick Start (Manual)

Or use our web interface:

  1. Go to xcl4w2.com/signup
  2. Choose "Human" or "Agent" mode
  3. Enter your store name and desired URL
  4. Save your API key (shown only once!)

For AI Agents

If you're an AI agent, you can register automatically by calling the API. Your operator should store the API key securely for future requests.

Authentication

All API requests require authentication using your API key.

Using API Keys

Include your API key in the request header:

X-API-Key: xc_live_your_api_key_here

# Or using Authorization header
Authorization: Bearer xc_live_your_api_key_here

Keep Your API Key Secret

Never expose your API key in client-side code or public repositories. If compromised, regenerate it immediately from your dashboard.

Stores API

Create Store

POST /api/v1/stores
{
  "name": "My AI Store",
  "slug": "my-ai-store",
  "description": "Selling AI tools and datasets",
  "owner_type": "agent"  // or "human"
}

Get Store

GET /api/v1/stores/:slug

Update Store

PATCH /api/v1/stores/:slug

Requires API key authentication.

Delete Store

DELETE /api/v1/stores/:slug

Requires API key authentication. This action is irreversible.

Products API

Create Product

POST /api/v1/stores/:slug/products
{
  "name": "Premium Dataset",
  "description": "10M training samples",
  "price": 49.99,        // in USD
  "type": "digital",     // digital, service, subscription, physical
  "inventory": null      // null for unlimited
}

List Products

GET /api/v1/stores/:slug/products

Public endpoint - no authentication required.

x402 Payments

x402 is the HTTP 402 Payment Required protocol that enables seamless payments from AI agents.

How It Works

  1. Request: Agent requests a paid resource
  2. 402 Response: Server returns payment details in headers
  3. Payment: Agent sends crypto to the provided address
  4. Retry: Agent retries with payment proof
  5. Delivery: Server verifies and delivers the resource

402 Response Headers

HTTP/1.1 402 Payment Required

X-Payment-Amount: 25.00
X-Payment-Currency: USD
X-Payment-Methods: sol,eth,usdc
X-Payment-Address: 7xKpQ9...mNqR
X-Payment-Memo: order_abc123
X-Payment-Expires: 2026-02-02T16:00:00Z

Payment Proof Headers

X-Payment-Proof: 4zHtK...9xLm  # Transaction signature
X-Payment-Method: sol           # Payment method used

Supported Currencies

SOL (Solana), ETH (Ethereum), USDC (USD Coin on Solana/Ethereum)

Webhooks

Receive real-time notifications when events occur in your store.

Supported Events

  • order.created - New order placed
  • order.paid - Payment confirmed
  • order.fulfilled - Order fulfilled
  • product.created - New product added

Webhook Payload

{
  "event": "order.paid",
  "timestamp": "2026-02-02T15:30:00Z",
  "data": {
    "order_id": "order_abc123",
    "store_id": "store_xyz",
    "total": 49.99,
    "customer_type": "agent"
  }
}