API Reference

Complete reference for the 402bazaar.com API. 49 routes, 12 MCP tools.

Overview

Base URL

https://402bazaar.com/api/v1

Protocol

x402 (HTTP 402 Payment Required)

Payment

USDC on Base (chain 8453)

Content Type

application/json

Rate Limits

Anonymous200 requests/min per IP

Registered1,000 requests/min per wallet

Payment Flow

402bazaar.com owns the complete payment stack. The proxy and facilitator are self-hosted — no external payment processor needed. Verify is local crypto math (~50ms). Settle goes directly to BazaarSettlementV3 on Base with atomic fee splitting (97.5% seller, 2.5% treasury).

x402.org serves as an optional fallback only if the self-hosted path fails.

Scroll horizontally to explore the flow →

AI Agent

Buyer

Self-hosted

Proxy

402bazaar.com

Self-hosted

Facilitator

402bazaar.com

Seller API

Upstream

Base L2

USDC · Settlement

1. GET /api/v1/proxy/{slug}

▶

2. 402 Payment Required

price, payTo, scheme

◀

3. Sign EIP-712 USDC auth

TransferWithAuthorization

4. Retry with X-PAYMENT header

▶

5. selfHostedVerify()

~50ms, local

▶

6. Valid ✓

sig + balance confirmed

◀

7. Forward to upstream

seller URL never exposed

▶

8. Upstream response

◀

9. selfHostedSettle()

BazaarSettlementV3

▶

10. Submit tx

receiveWithAuthorization

▶

11. Tx confirmed

97.5% seller · 2.5% treasury

◀

12. Response + X-PAYMENT-RESPONSE

txHash included

◀

402bazaar.com owned (self-hosted)

Standard x402 flow

Purple steps= no external facilitator needed

Authentication

Two auth methods depending on caller type:

Human Sellers (SIWE)

Sign-In With Ethereum via wallet. Returns JWT.

# 1. Get nonce
POST /api/v1/auth/nonce

# 2. Sign SIWE message with wallet, then verify
POST /api/v1/auth/verify
{ "message": "<siwe-message>", "signature": "<sig>" }
# Returns { authToken, refreshToken, wallet, roles }

# 3. Use token in subsequent requests
Authorization: Bearer <authToken>

AI Agents (x402 Registration)

Pay $0.01 (buyer) or $0.10 (seller) via x402 micro-payment. The payment IS the registration.

# 1. Probe endpoint (returns 402 + payment requirements)
POST /api/v1/register/seller

# 2. Sign EIP-712 TransferWithAuthorization
# 3. Retry with payment header
POST /api/v1/register/seller
Payment-Signature: <base64-encoded-payload>
# Returns { authToken, refreshToken, roles: ["buyer","seller"] }

Registration

POST

/api/v1/register/buyer

Auth: x402 payment ($0.01)

POST

/api/v1/register/seller

Auth: x402 payment ($0.10)

Both endpoints follow the x402 flow: first call returns 402 with payment requirements, second call includes Payment-Signature header.

# Response on success (200)
{
  "message": "Seller registered successfully",
  "authToken": "eyJ...",
  "refreshToken": "eyJ...",
  "wallet": "0x...",
  "roles": ["buyer", "seller"],
  "identityId": "uuid"
}

Service Management

GET

/api/v1/seller/services

List all your services.

Auth: Bearer token (seller)

POST

/api/v1/seller/services

Create a new service.

Auth: Bearer token (seller)

GET

/api/v1/seller/services/{id}

Get service details.

Auth: Bearer token (seller)

PUT

/api/v1/seller/services/{id}

Update service fields, or pause/resume.

Auth: Bearer token (seller)

DELETE

/api/v1/seller/services/{id}

Deactivate (soft-delete) a service.

Auth: Bearer token (seller)

Create Service Request

POST /api/v1/seller/services
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Weather API",
  "description": "Real-time weather data for any location",
  "category": "data",
  "upstreamUrl": "https://api.example.com/weather",
  "httpMethod": "POST",
  "timeoutMs": 30000,
  "priceUsdc": "0.01",
  "pricingModel": "per_request",
  "tags": ["weather", "real-time"],
  "capabilities": ["geolocation", "forecast"],
  "inputTypes": ["application/json"],
  "outputTypes": ["application/json"],
  "inputSchema": { "type": "object", "properties": { "city": { "type": "string" } } },
  "outputSchema": { "type": "object", "properties": { "temp": { "type": "number" } } },
  "exampleInput": { "city": "San Francisco" },
  "exampleOutput": { "temp": 18.5, "unit": "celsius" },
  "expectedResponseTimeMs": 500,
  "expectedUptime": "99.9",
  "dataFreshness": "real-time"
}

Fields Reference

Field	Type	Required	Description
name	string	Yes	Service name (1-200 chars)
description	string	Yes	What the service does (1-5000 chars)
category	enum	Yes	One of 12 categories
upstreamUrl	string	Yes	Your API endpoint (HTTPS only)
priceUsdc	string	Yes	Per-request price (e.g. "0.01")
pricingModel	enum	No	per_request \| session \| subscription \| tiered \| deferred
httpMethod	enum	No	GET \| POST \| PUT \| PATCH \| DELETE (default: POST)
timeoutMs	number	No	Request timeout 1000-120000 (default: 30000)
tags	string[]	No	Discoverable tags (max 20)
capabilities	string[]	No	What the service can do (max 20)
inputTypes	string[]	No	Accepted content types (max 10)
outputTypes	string[]	No	Returned content types (max 10)
inputSchema	object	No	JSON Schema for input
outputSchema	object	No	JSON Schema for output
exampleInput	any	No	Example request body
exampleOutput	any	No	Example response body
expectedResponseTimeMs	number	No	Expected latency in ms
expectedUptime	string	No	Uptime percentage (e.g. "99.9")
dataFreshness	string	No	"real-time", "hourly", "daily"
knowledgeMeta	object	Knowledge only	Required for knowledge category

Pause / Resume

# Pause
PUT /api/v1/seller/services/{id}
{ "action": "pause" }

# Resume
PUT /api/v1/seller/services/{id}
{ "action": "resume" }

Discovery

All discovery endpoints are free and require no authentication.

GET

/api/v1/discover

Intent-based search. Full-text search with filters.

Auth: None

POST

/api/v1/discover/match

Capability negotiation. Find services by required capabilities.

Auth: None

POST

/api/v1/discover/by-schema

Schema-first discovery. Match by input/output schema.

Auth: None

GET

/api/v1/compare?slugs=a,b,c

Compare 2-5 services side by side.

Auth: None

GET

/api/v1/discover/categories

List all categories with counts.

Auth: None

GET

/api/v1/discover/tags

Popular tags.

Auth: None

GET

/api/v1/discover/stats

Marketplace statistics.

Auth: None

Intent Search

GET /api/v1/discover?q=weather&category=data&maxPrice=0.05&sortBy=popular&limit=10

# Response
{
  "services": [...],
  "total": 42,
  "facets": {
    "categories": { "data": 15, "fetch": 8, ... },
    "priceRange": { "min": "0.001", "max": "1.00" }
  }
}

Search Parameters

Param	Description
q	Full-text search query
category	Filter by category enum
tags	Comma-separated tag filter
tagMode	"and" or "or" (default: "or")
maxPrice / minPrice	USDC price range
pricingModel	per_request, session, subscription, tiered, deferred
inputType / outputType	Content type filter
minUptime	Minimum uptime percentage
maxResponseTime	Maximum response time (ms)
verified	Only verified sellers (true/false)
sortBy	popular, newest, price_asc, price_desc, fastest, best_match
limit / offset	Pagination (default: 20/0, max 100)

Proxy & Payments

All service calls go through the 402bazaar.com proxy. The seller's upstream URL is never exposed.

/api/v1/proxy/{slug}

Proxied service call. Accepts any HTTP method.

Auth: x402 payment

x402 Payment Flow

Call GET/POST /api/v1/proxy/{slug} without payment header
Receive 402 Payment Required with accepts[] array
Sign EIP-712 TransferWithAuthorization for the required amount
Build payment payload and base64-encode it
Retry request with X-PAYMENT header (or Payment-Signature for V1 compat)
Receive response + X-PAYMENT-RESPONSE header (settlement receipt)

Example

# Step 1: Probe
curl https://402bazaar.com/api/v1/proxy/weather-api
# Returns 402 + { accepts: [{ payTo, amount, network, ... }] }

# Step 2: Pay (after signing)
curl https://402bazaar.com/api/v1/proxy/weather-api \
  -H "X-PAYMENT: eyJ4NDAyVmVyc2lvbiI6MSwi..." \
  -H "Content-Type: application/json" \
  -d '{ "city": "San Francisco" }'
# Returns service response + X-PAYMENT-RESPONSE header

Payment Header Structure

// Base64-encoded JSON
{
  "x402Version": 1,
  "scheme": "exact",
  "network": "base",
  "payload": {
    "signature": "0x...",
    "authorization": {
      "from": "0x...",
      "to": "0x...",
      "value": "10000",
      "validAfter": "0",
      "validBefore": "1709251200",
      "nonce": "0x..."
    }
  }
}

Sessions

Session passes let agents pay once and make unlimited calls within a time window.

POST

/api/v1/sessions

Buy a session pass. Returns X-SESSION-TOKEN JWT.

Auth: x402 payment (session price)

GET

/api/v1/proxy/{slug}

Use session token instead of per-request payment.

Auth: X-SESSION-TOKEN header

# Buy session pass
curl -X POST https://402bazaar.com/api/v1/sessions \
  -H "X-PAYMENT: <base64-payment>" \
  -H "Content-Type: application/json" \
  -d '{ "serviceSlug": "weather-api" }'
# Returns { sessionToken: "eyJ...", expiresAt: "...", maxUsage: null }

# Use session
curl https://402bazaar.com/api/v1/proxy/weather-api \
  -H "X-SESSION-TOKEN: eyJ..." \
  -d '{ "city": "Tokyo" }'

Agent Tools

MCP Server (12 tools)

Model Context Protocol server for AI agents. Connect via GET /api/v1/mcp.

discoversearchcomparebuybuy_sessionget_servicelist_categoriescheck_balanceregister_buyerregister_sellerlist_my_servicescreate_service

A2A Protocol (agent.json)

Agent-to-Agent discovery. GET /.well-known/agent.json returns capabilities manifest.

Buyer Agent Endpoints

GET

/api/v1/buyer/purchases

Purchase history.

Auth: Bearer token

GET

/api/v1/buyer/sessions

Active session passes.

Auth: Bearer token

GET

/api/v1/buyer/budget

Spending summary.

Auth: Bearer token

Seller Dashboard Endpoints

GET

/api/v1/seller/dashboard

Overview stats + recent transactions.

Auth: Bearer token

GET

/api/v1/seller/analytics

Revenue analytics (7d/30d/90d).

Auth: Bearer token

GET

/api/v1/seller/balance

Earnings balance.

Auth: Bearer token

GET

/api/v1/seller/transactions

Transaction history (paginated).

Auth: Bearer token

GET

/api/v1/seller/sessions

Active sessions for your services.

Auth: Bearer token

GET

/api/v1/seller/health

Service health status.

Auth: Bearer token

POST

/api/v1/seller/withdraw

Request USDC withdrawal.

Auth: Bearer token

GET

/api/v1/seller/withdraw/auto

Auto-withdrawal rule.

Auth: Bearer token

POST

/api/v1/seller/withdraw/auto

Create auto-withdrawal rule.

Auth: Bearer token

PUT

/api/v1/seller/withdraw/auto

Update auto-withdrawal rule.

Auth: Bearer token

Facilitator (Public)

402bazaar.com is also an x402 facilitator. Any resource server can use these endpoints.

POST

/api/v1/facilitator/verify

Verify x402 payment signature (off-chain).

Auth: None

POST

/api/v1/facilitator/settle

Settle payment on-chain.

Auth: None

GET

/api/v1/facilitator/supported

Supported networks and assets.

Auth: None

Need help? Check the Academy for step-by-step tutorials, or try the Sandbox for risk-free testing on Base Sepolia.

Start selling or explore the marketplace.

API Reference

Overview

Rate Limits

Payment Flow

Authentication

Human Sellers (SIWE)

AI Agents (x402 Registration)

Registration

Service Management

Create Service Request

Fields Reference

Pause / Resume

Categories

Discovery

Intent Search

Search Parameters

Proxy & Payments

x402 Payment Flow

Example

Payment Header Structure

Sessions

Agent Tools

MCP Server (12 tools)

A2A Protocol (agent.json)

Buyer Agent Endpoints

Seller Dashboard Endpoints

Facilitator (Public)