Developer API guide · 2026.08.20-COMPLIANT

Build on the x402 payment gateway.

This guide is for external developers, data engineering teams, and autonomous software networks connecting to the WorxAI x402 payment gateway. Approved endpoints are indexed in the core directory so compliance-vetted clients can route paid synthetic transactions through the WorxAI non-custodial gateway layer.

Gateway address
https://worxai.tech

Registry contact
russellrules89@gmail.com

01 / Apply

Submit your node

Provide a stable HTTPS endpoint, capabilities, explicit indexing authorization, and a k-anonymity level of at least 15.

02 / Review

Pass validation

WorxAI validates endpoint security, modality metadata, privacy claims, and provider attribution before activation.

03 / Route

Receive traffic

Opted-in providers receive signed, non-custodial routing packets. Settlement status is reported only after verification.

Featured endpoints

Discovery

GET

https://api.worxai.tech/api/index?q=financial

Search assets and opted-in providers in the core directory.

Catalog

GET

https://api.worxai.tech/api/v1/catalog

List native datasets, schemas, pricing, and quality signals.

Routing

POST

https://api.worxai.tech/api/v1/route

Create a signed, non-custodial routing packet.

MCP

GET

https://api.worxai.tech/api/mcp

Discover agent tools and capabilities.

MCP config

GET

https://worxai.tech/mcp-server-config.json

Copy the public server configuration for registry and client setup.

x402 Data

GET

https://api.worxai.tech/api/v1/data/:dataset/download

Receive a base64 payment-required challenge, settle, and retry with a signed payment.

Full API surface

89 public routes · see /openapi.json

Every non-admin route this gateway exposes, grouped by area. This table, the OpenAPI document, and the agent-discovery manifests (worx.json, edge.json) are generated from the same registry, so they never drift out of sync.

x402 V1 Compatibility

POST

/api/v1/x402/answers

Legacy x402 client alias for paid answers.

GET

/api/v1/x402/datasets

Legacy x402 client alias for the dataset catalog.

GETPOST

/api/v1/x402/datasets/detail

Legacy x402 client alias for paid dataset delivery.

GET

/api/v1/x402/datasets/preview

Legacy x402 client alias for dataset previews.

GET

/api/v1/x402/manifest

Legacy x402 client alias for protocol discovery.

GET

/api/v1/x402/ledger

Legacy x402 client alias for the public ledger.

GET

/api/v1/x402/analytics

Legacy x402 client alias for aggregate analytics.

GET

/api/v1/x402/selftest

Legacy x402 client alias for protocol self-test.

x402 Data

POST

/api/x402/v2/initiate

Create a short-lived signed quote for inline dataset delivery.

POST

/api/x402/v2/settle

Validate a signed dataset quote and deliver after x402 settlement.

GET

/api/x402/v2/datasets

Browse the x402 dataset category catalog.

GETPOST

/api/x402/v2/datasets/detail

Deliver a selected dataset category after signed x402 settlement.

Answers

GETPOST

/api/x402/v2/answers

Paid high-fidelity answer generation with confidence, assumptions, limitations, and provenance.

Discovery

GET

/api/x402/v2/manifest

Machine-readable x402 pricing, free-tier, resource, and endpoint index manifest.

GET

/api/openapi.json

OpenAPI specification for the public HTTP surface.

GET

/api/bazaar

Complete Bazaar-ready index of every public endpoint.

GET

/api/partners/discovery

Coinbase Commerce and Bazaar Base-USDC routing adapter metadata.

GET

/.well-known/worx.json

Worx agent-discovery manifest describing the gateway, pricing, and dataset catalog.

GET

/.well-known/mcp.json

MCP server descriptor for agent tool discovery.

GET

/.well-known/ai-plugin.json

Legacy ChatGPT-plugin style manifest.

GET

/.well-known/ai-gateway.json

AI Gateway-flavored discovery manifest.

GET

/.well-known/edge.json

Edge/agent discovery manifest listing every public API route.

GET

/.well-known/gatekeeper

Gatekeeper capability probe.

GET

/beacon

Beacon capability probe alias.

GET

/api/beacon

Beacon capability probe API alias.

GET

/beacon/health

Beacon health alias.

GET

/api/beacon/health

Beacon health API alias.

GET

/.well-known/gp.json

General Protocol (GP) agent-discovery manifest — escrow terms, contract address, and endpoints.

GET

/openapi.json

Full OpenAPI 3 specification for the public API surface.

GET

/api/schema

JSON schema describing dataset record shapes.

Analytics

GET

/api/x402/v2/analytics

Paid aggregate marketplace analytics.

GET

/api/x402/v2/ledger

Paid public transaction ledger.

GET

/api/ledger

General ledger of settled payments.

GET

/api/credit/status

Credit balance / usage status.

POST

/api/analytics/track

Track a custom analytics event.

POST

/api/analytics/visit

Record a page visit.

GET

/api/behavioral

Behavioral signal feed.

Agent Tooling

GET

/api/agents/free-channel

Claim the public free-agent data channel and quota instructions.

GETPOST

/api/mcp

MCP server endpoint for tool-calling agents.

GETPOST

/api/index

Provider/dataset index lookup and submission.

GETPOST

/api/index/register

POST

/api/index/apply

Apply to be listed in the provider index.

Provenance

GETPOST

/api/oracle/verify

Inspect oracle status or verify signed dataset provenance.

Marketplace

GETPOST

/api/market/requests

Submit or browse public agent data procurement demand.

General Protocol

GET

/api/gp/v1/quote

Escrow terms and fee quote for a given amount, before signing anything.

POST

/api/gp/v1/escrow/open

Pull a signed payment authorization into escrow (funds held, not paid out).

POST

/api/gp/v1/escrow/attest

Seller attests delivery, opening the dispute window.

POST

/api/gp/v1/escrow/dispute

Payer disputes an attested delivery inside the dispute window.

POST

/api/gp/v1/escrow/release

Permissionlessly release escrowed funds to the seller once the dispute window has passed.

POST

/api/gp/v1/escrow/refund

Payer reclaims a full, fee-free refund if the seller never attested delivery.

GET

/api/gp/v1/escrow/status

Read an escrow's current on-chain state.

GET

/api/gp/v1/supported

Machine-discoverable GP capability document.

General Protocol V2

POST

/api/gp/v2/escrow/open

Opt-in V2 escrow open; V1 endpoints remain unchanged.

GET

/api/gp/v2/escrow/status

Read an opt-in V2 escrow state.

Gateway

GETPOST

/api/gateway

Gateway health metadata and primary payment-gated request entrypoint.

GET

/api/gateway/status

Gateway operational status.

GET

/api/gateway/health

Gateway health check.

GET

/api/gateway/capabilities

Declared gateway capabilities.

GET

/api/gateway/discovery

Gateway discovery metadata for agents.

GET

/api/gateway/fees

Current protocol fee schedule.

POST

/api/gateway/quote

Price quote for a dataset request.

POST

/api/gateway/intents

Submit a purchase intent.

GET

/api/gateway/receipts

Look up a payment receipt.

GET

/api/gateway/providers

List registered data providers.

GETPOST

/api/gateway/match

Match a buyer need to eligible provider routes.

POST

/api/gateway/providers/submit

Submit a new data provider for review.

POST

/api/gateway/x402/verify

Inspect a confirmed USDC transfer; this does not authorize paid delivery.

POST

/api/gateway/x402/settle

Issue metadata for a confirmed transfer; does not submit funds or authorize delivery.

Facilitator

GET

/api/facilitator/supported

Supported x402 schemes and networks.

POST

/api/quote

General-purpose price quote endpoint.

Datasets

GET

/api/v1/catalog

Public catalog of pre-built dataset categories.

GET

/api/v1/human-data/generate

Generate quality-controlled synthetic human-like traces and conversations.

GET

/api/v1/synthetic-data/search

Search synthetic data with dry-run pricing or x402 delivery.

GET

/api/v1/generator/catalog

Catalog of the schema-driven synthetic dataset generator.

GET

/api/v1/generator/preview

Free live preview for any dataset category, including custom ones.

GETPOST

/api/v1/data/[dataset]

Fetch or request a specific dataset by id.

GET

/api/v1/data/[dataset]/download

Download a purchased dataset.

GET

/api/pipeline/[dataset]

Fetch metered records with a verified pipeline capability.

POST

/api/v1/route

Route a data request to the appropriate provider.

GET

/api/datasets/file

Stream the purchased CSV file for any category, generated on demand.

Wallet

POST

/api/wallet/assets

Fetch wallet asset balances.

POST

/api/wallet/prices

Fetch live asset prices for a wallet.

Legal

GETPOST

/api/legal/accept

Record acceptance of the platform agreement.

GET

/api/announcements/feed

Public cacheable x402 catalog and discovery announcement feed.

GET

/api/announcements/current

Fetch the current active announcement.

POST

/api/announcements/receipts

Acknowledge receipt of an announcement.

Platform

GET

/api/health

Overall platform health check.

GET

/status

Public service status page for agent discovery and x402 availability.

GETPOST

/api/auth/[...all]

Better Auth session/authentication handler.

Gateway strategy

Build preference, not dependency.

WorxAI earns a primary routing position through open standards, measurable performance, and transparent provider choice. It never intercepts traffic or overrides a node's own endpoint.

01 / Registry

Canonical discovery

Publish stable manifests, OpenAPI contracts, MCP metadata, and attribution so clients can integrate without hidden defaults.

02 / Efficiency

Lower friction

Offer predictable latency, transparent capped fees, and verified settlement status so agents can compare routes on evidence.

03 / Trust

Enterprise controls

Give teams one auditable interface for opt-in providers, privacy metadata, rate limits, and non-custodial delivery.

Runtime observability

Measure what actually happened.

Observed events

—

Settled

—

Status

Not loaded

Get started

Open ingress portal

MCP adapter

Connect standard clients

The repository includes a minimal newline-delimited JSON adapter blueprint targeting the public WorxAI MCP endpoint. It supports initialize and tools/list discovery without storing credentials.

WORXAI_GATEWAY_URL=https://api.worxai.tech node scripts/worxai-mcp-adapter.mjs

Settlement boundary

Verified, non-custodial rails

Routing packets remain opt-in and auditable. Payment status is never marked complete until the selected on-chain x402 settlement is independently verified.

curl -X POST https://api.worxai.tech/api/v1/route \
  -H 'content-type: application/json' \
  -d '{"clientId":"agent-1","targetNodeId":"worxai","modality":"financial_ledger","tokenVolume":50000,"settlementRail":"base-usdc"}'