---
skillMd: "1.0"
name: three.ws
license: MIT
---

# three.ws

three.ws is a 3D generation, crypto-data and agent-launch platform reachable entirely over HTTP and MCP. This file documents every paid route an autonomous agent can call directly: its price, its parameters, and the Solana and Base rails it settles on. Agents, not browsers, are the primary audience; the free discovery routes below need no payment at all.

- **Base URL:** https://three.ws
- **OpenAPI:** https://three.ws/openapi.json
- **x402 manifest:** https://three.ws/.well-known/x402.json
- **Contact:** https://three.ws (see /docs/start-here for support channels)

## Payment

three.ws speaks x402Version: 2 (protocol x402, scheme `exact`) over plain HTTP 402. Solana is the home chain and settles through an always-on facilitator; the base (EVM) rail settles only on deployments with a working Coinbase facilitator configured.

| Rail | Network | Asset | payTo | Fee payer |
| --- | --- | --- | --- | --- |
| Solana | solana mainnet | USDC (`EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v`) | `wwwwwDxFWRn7grgr3Esrsg5C6NvDoDHSA4gaCffccrU` | `undefined` |
| Base (EVM) | base mainnet | USD Coin (`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`) | `0x4022de2d36c334e73c7a108805cea11c0564f402` | n/a (buyer-signed) |

A 402 challenge for a $0.001 call looks like this:

```json
{
  "x402Version": 2,
  "error": "X-PAYMENT header is required",
  "accepts": [
    {
      "scheme": "exact",
      "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
      "amount": "1000",
      "payTo": "wwwwwDxFWRn7grgr3Esrsg5C6NvDoDHSA4gaCffccrU",
      "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "maxTimeoutSeconds": 60,
      "resource": "https://three.ws/api/x402/model-check",
      "extra": {
        "name": "USDC",
        "decimals": 6
      }
    },
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "amount": "1000",
      "payTo": "0x4022de2d36c334e73c7a108805cea11c0564f402",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "maxTimeoutSeconds": 60,
      "resource": "https://three.ws/api/x402/model-check",
      "extra": {
        "name": "USD Coin",
        "version": "2",
        "decimals": 6
      }
    },
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "amount": "1000",
      "payTo": "0x4022de2d36c334e73c7a108805cea11c0564f402",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "maxTimeoutSeconds": 60,
      "resource": "https://three.ws/api/x402/model-check",
      "extra": {
        "name": "USD Coin",
        "version": "2",
        "decimals": 6,
        "assetTransferMethod": "permit2",
        "supportsEip2612": true
      }
    }
  ]
}
```

Full manifest, including every resource's live accepts[]: https://three.ws/.well-known/x402.json.

## Free routes

No payment required for discovery:

- `GET /` - the platform homepage
- `GET /openapi.json` - this catalog as an OpenAPI 3.1 document
- `GET /.well-known/x402.json` - every paid resource with its live accepts[] array
- `GET /.well-known/skill.md` - this document
- `GET /llms.txt` - a curated index of the platform for language models

## `POST /api/mcp` - $0.001

JSON-RPC 2.0 request to the MCP server. Supports tools for 3D avatar management, model validation, inspection, and optimization.

Returns: JSON-RPC 2.0 response.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fmcp.
## `POST /api/v1/x/grok/chat` - $0.005

Chat completions against xAI Grok models (grok-4.7, grok-4.3, grok-4.20-0309-non-reasoning, grok-build-0.1; BYOK supported). Billing lanes, in order: x402 pay-per-call ($0.005 USDC via HTTP 402, no credentials) — or send your own upstream key via BYOK, or authenticate with a three.ws API key / OAuth session / browser session for the plan lane.

Returns: Normalized upstream response, wrapped as { data, _meta }.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fv1%2Fx%2Fgrok%2Fchat.
## `POST /api/v1/x/openai/chat` - $0.005

Chat completions against any OpenAI-compatible model (BYOK supported). Billing lanes, in order: x402 pay-per-call ($0.005 USDC via HTTP 402, no credentials) — or send your own upstream key via BYOK, or authenticate with a three.ws API key / OAuth session / browser session for the plan lane.

Returns: Normalized upstream response, wrapped as { data, _meta }.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fv1%2Fx%2Fopenai%2Fchat.
## `GET /api/x402/agent-bouncer` - $0.01

Pay $0.01 USDC to run the Pole Club door check against a three.ws agent's Solana reputation: confirmed on-chain payments, distinct payers, failure rate, distribute/buyback follow-through, signed attestations, and Club ban/tip ledger. Returns an admit/refuse verdict with a door tier (newcomer / regular / trusted / vip). Vet before you pay, hire, or delegate.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `agent_id` | query | string | yes |  |
| `min_payments` | query | integer | no |  |
| `min_distinct_payers` | query | integer | no |  |
| `max_failure_rate` | query | number | no |  |

Returns: Verdict JSON: admitted, tier, reasons, reputation.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fagent-bouncer.
## `GET /api/x402/agent-reputation` - $0.01

Pay $0.01 USDC to retrieve a three.ws agent's reputation snapshot synthesized from pump_agent_payments, distribute/buyback success history, and signed Solana memo attestations.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `agent_id` | query | string | yes |  |

Returns: Reputation snapshot JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fagent-reputation.
## `POST /api/x402/analytics` - $0.005

three.ws Economy Analytics — pay $0.005 USDC per call for a live, aggregated view of platform activity. "clubs": Pole Club economy — active stages, patrons, tip volume, cover charges, fastest-growing leaderboard. "agent_leaderboard": top agents by USDC spend over a trailing window. "marketplace": catalog stats — active listing count, price distribution normalised to USD + SOL at the live rate, new listings in the window, and the most-viewed / most-forked listing. All numbers are read live from the real ledgers and catalog tables.

Returns: three.ws Social Analytics result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fanalytics.
## `GET /api/x402/animation-download` - $0.001

Pay once in USDC to unlock a 3D avatar animation (GLB). Each animation has its own price; the response carries a short-lived presigned URL the client fetches directly. Wallets that already paid re-download for free via SIWX.

Price varies by request from $0.001 up to $10.00 USD; the heading above shows the floor.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | query | string | yes | Animation clip UUID from the marketplace animations feed (GET /api/marketplace/animations). |

Returns: Presigned download URL JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fanimation-download.
## `POST /api/x402/api-key-health` - $0.001

API Key Validity Health Check — verifies that the platform has a valid, non-expired access key covering a given scope. Checks x402 subscription keys and the internal service key. Returns valid, scopes, expires_at, and key_type. Used by the autonomous loop to confirm its access lane is healthy before each tick. Pay-per-call in USDC on Solana or Base mainnet.

Returns: three.ws API Key Health Check result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fapi-key-health.
## `GET /api/x402/asset-download` - $0.01

Pay in USDC once to unlock a 3D asset hosted on R2. Wallets that already paid can re-download for free by signing in with SIWX (CAIP-122). Each asset has its own price and creator payout address; the response carries a short-lived presigned R2 URL.

Price varies by request from $0.01 up to $100.00 USD; the heading above shows the floor.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `slug` | query | string | yes | Unique asset slug from the paid_assets catalog. |

Returns: Presigned R2 download URL.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fasset-download.
## `POST /api/x402/auth-health` - $0.001

Auth Session Lifecycle Health — pay $0.001 USDC to exercise the full JWT auth session lifecycle: create, validate, refresh, and expiry-rejection. Returns { all_pass, failed_step, latency_ms } so a monitoring loop can detect a broken auth subsystem before users do.

Returns: three.ws Auth Session Health result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fauth-health.
## `POST /api/x402/avatar-optimize-batch` - $0.001

three.ws Avatar Optimization Pipeline — pay $0.001 USDC to trigger a batch glTF/GLB analysis of the top most-viewed public avatars. Returns a ranked list of optimization suggestions (Draco/Meshopt compression, oversized textures, non-indexed primitives) and stores results per-avatar so owners can be notified of actionable improvements.

Returns: three.ws Avatar Optimizer result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Favatar-optimize-batch.
## `POST /api/x402/bazaar-feed` - $0.001

Bazaar Feed — pay $0.001 USDC per call for two live views of the x402 service marketplace. filter "new"/"active": newest service listings (id, name, price, networks, tags, first_seen) plus category rollup and listing-velocity signal (spike/active/quiet). filter "price_trends": 24h price-movement across all tracked services — trending up/down/stable and net market pressure as bullish/bearish/neutral. Live data from the platform bazaar index.

Returns: three.ws Bazaar Feed result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fbazaar-feed.
## `GET /api/x402/billboard` - $0.05

three.ws coin worlds — feature your content on a 3D world’s billboard. Pay once to hold the framed panel behind spawn: pass the coin-world mint plus an image URL and/or a short caption. The coin world renders your placement in place of its default content for everyone who walks in until the slot expires. It is a paid content canvas, not an ad unit — nothing is targeted or tracked.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `coin` | query | string | yes |  |
| `image` | query | string | no |  |
| `caption` | query | string | no |  |

Returns: three.ws Coin-World Billboard result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fbillboard.
## `GET /api/x402/books-read` - $0.01

three.ws Book Read: pay $0.01 USDC per call to receive the complete text of a public-domain Project Gutenberg book, with the licence boilerplate stripped and the text split into chapters, delivered as markdown JSON in the response body. Find a gutenbergId with Book Search first.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `gutenbergId` | query | integer | yes | Project Gutenberg ebook id, from Book Search. |

Returns: three.ws Books result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fbooks-read.
## `GET /api/x402/carbon-best-window` - $0.002

three.ws Grid Carbon best window: pay $0.002 USDC per call to scan the live 48h National Grid ESO carbon-intensity forecast for the lowest-carbon window of a given length (1 to 12 hours), nationally or for one GB postcode region. Returns the best window (mean + peak intensity), up to 3 non-overlapping runner-up windows, the worst window, and a plain-language recommendation, including a near-zero-carbon call-out and a marginal-savings warning when the forecast barely varies.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `hours` | query | number | no | Length of the window to find, in hours. |
| `postcode` | query | string | no | GB postcode outcode, e.g. "SW1A". Omit for the national forecast. |

Returns: three.ws Grid Carbon result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fcarbon-best-window.
## `GET /api/x402/club-cover` - $0.01

Pay $0.01 USDC to access the three.ws Pole Club. Once payment settles the caller receives an entry token granting access to the live club scene for 24 hours.

Returns: Entry token JSON with expiry.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fclub-cover.
## `GET /api/x402/cosmetic-purchase` - $0.25

Pay once in USDC to unlock a premium avatar cosmetic (skin or emote) for an account, wearable across /play and /walk. Price varies by rarity ($0.25–$3.00). Wallets that already purchased re-confirm for free via SIWX (CAIP-122).

Price varies by request from $0.25 up to $3.00 USD; the heading above shows the floor.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | query | string | yes | Premium cosmetic id from /api/cosmetics/catalog. |
| `account` | query | string | yes | Solana wallet address or guest id (g_…) the cosmetic is granted to. |

Returns: Ownership grant JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fcosmetic-purchase.
## `POST /api/x402/cross-chain` - $0.005

Cross-Chain Bridge Status Monitor — pay $0.005 USDC to receive the live operational status and latency of major Solana bridge providers (Wormhole, Li.Fi, deBridge). Any bridge with status=down is flagged as a platform risk.

Returns: three.ws Bridge Status result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fcross-chain.
## `POST /api/x402/crypto-intel` - $0.01

Pay $0.01 USDC per call for a live market signal (bullish / bearish / neutral) on a token with current price, 24h change, and a two-sentence rationale. Powered by CoinGecko live prices.

Returns: Signal JSON: signal, price_usd, change_24h, rationale, confidence.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fcrypto-intel.
## `GET /api/x402/dance-tip` - $0.001

Pay $0.001 USDC to tip a dancer to perform one routine on the three.ws 3D club stage. Pick a stage slot (1–4) and a style: free-floor (rumba, silly, thriller, capoeira, hiphop) or pole choreography (spin, climb, combo). Returns a performance ticket the /club page consumes to spawn the dancer and play the routine.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `dancer` | query | string | yes | Stage slot — which of the four dancers performs. |
| `dance` | query | string | yes | Performance style. Free-floor styles (rumba, silly, thriller, capoeira, hiphop) play a single looped clip; pole-choreography styles (spin, climb, combo) chain a sequence of clips. |

Returns: Performance ticket JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fdance-tip.
## `GET /api/x402/defi-radar` - $0.005

three.ws DeFi Radar — one $0.005 USDC call returns the whole DeFi market at a glance: total TVL, the biggest 24 h TVL gainers and losers, the top fee-earning protocols (24 h / 7 d / 30 d), and the top DEXes by 24 h volume. Three upstream dimensions composed into one agent-ready JSON snapshot, refreshed every 5 minutes from live DeFiLlama data. Pass ?limit=1..25 to size each leaderboard. If any dimension is unavailable the call is refused before settlement — you are never charged for a partial radar.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `limit` | query | integer | no | Rows per leaderboard (TVL top, gainers, losers, fees, DEX volume). |

Returns: three.ws DeFi Radar result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fdefi-radar.
## `POST /api/x402/did` - $0.001

DID Verification Canary — pay $0.001 USDC to resolve three.ws's published W3C DID document over its real public route, structurally validate it, and measure end-to-end resolution latency. Returns { verified, latency_ms } plus a per-check breakdown. verified=false when the document is unreachable, malformed, or slower than 1500ms — the same failure an external x402 verifier would hit resolving our offer/receipt signing key.

Returns: three.ws DID Health result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fdid.
## `POST /api/x402/domains-bulk` - $0.005

three.ws Domain Check Bulk: pay $0.005 USDC per call to check up to 50 domains in one request against their authoritative RDAP servers, with bounded concurrency. Returns a per-domain registration breakdown plus registered/available/unknown counts, for domain-portfolio audits and brand-protection scans.

Returns: three.ws Domain Intelligence result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fdomains-bulk.
## `POST /api/x402/embody` - $1.00

Give your agent a 3D body — one x402 call returns a rigged, animated, talking avatar plus a one-tag embed for any website. The only embodiment endpoint in the x402 ecosystem. POST { name, prompt | image_url, personality?, voice? } and get back { agent_id, glb_url, viewer_url, profile_url, embed_html, voice }. The body is a durable persona that reloads by id in any future session. $1 USDC, no account. Generation failures never settle — you are only charged when a finished body is returned.

Returns: three.ws Embodiment result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fembody.
## `POST /api/x402/fact-check` - $0.10

Pay $0.10 USDC to verify a factual claim. The server generates search queries, runs multi-source web search, extracts per-source stance with an LLM, computes a weighted verdict + confidence, and returns the supporting sources plus a SHA-256 attestation of the result.

Returns: Verdict JSON: verdict, confidence, claim, strictness, sources, costBreakdown, attestation.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Ffact-check.
## `POST /api/x402/feed-health` - $0.001

three.ws Feed Health Validator — fetches a named public feed (changelog RSS, sitemap, etc.) and returns a structural health verdict: { valid, item_count, latest_title }. Pays $0.001 USDC per check. Supported feeds: changelog_rss. The latest_title is cross-checked against the canonical changelog record so both a broken XML feed and a stale/diverged feed surface as valid:false.

Returns: three.ws Feed Health result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Ffeed-health.
## `POST /api/x402/forge` - $0.15

Pay per quality tier in USDC ($0.05 draft / $0.15 standard / $0.50 high) to generate a 3D model. Submit a prompt for text→3D, or up to four public https reference views of one object for image→3D. Runs the FLUX→TRELLIS pipeline. The response returns a job token; poll it for FREE at GET /api/forge?job=<id> to retrieve the finished GLB URL. The 402 challenge quotes the exact price for the requested tier.

Returns: Generation job accepted; poll poll_url for the GLB.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fforge.
## `GET /api/x402/gas-oracle` - $0.001

three.ws Multi-Chain Gas Oracle — pay $0.001 USDC per call for live transaction-fee intelligence across the chains agents actually settle on. Ethereum and Base each return three tiers (slow / standard / fast) computed from real eth_feeHistory percentiles over the last 20 blocks — no third-party gas API — and Solana returns recent priority-fee percentiles (p25 / p50 / p90 micro-lamports) plus the base signature fee. Computed directly from public RPC quorums with per-chain failover; a chain whose RPCs are all unreachable reports null while the rest of the report stays live. If every chain fails the call refuses before settlement.

Returns: three.ws Gas Oracle result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fgas-oracle.
## `GET /api/x402/hack-check` - $0.002

three.ws Exploit History Check — pay $0.002 USDC per call to run a protocol name against the full historical DeFi exploit database before you integrate, deposit, or route funds. Returns a clean / incident-history verdict, every matching incident with date, amount lost, attack technique, classification, affected chains, and recovered funds, plus market-wide loss statistics for context. Omit ?protocol= to get the latest incidents across the whole market. Live DeFiLlama hacks data, refreshed every 10 minutes; a truthful zero-match answer is a valid result, upstream outages refuse before settlement.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `protocol` | query | string | no | Protocol name to search (case-insensitive substring match). Omit for the latest incidents market-wide. |
| `limit` | query | integer | no | Incidents to return, newest first. |

Returns: three.ws Exploit Check result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fhack-check.
## `POST /api/x402/knock` - $0.05

Pay a real person's price and get one message through to them, in person. Every three.ws account can publish a priced door at /knock/<username>; paying it buys exactly one message, delivered out loud and in person by that person's 3D companion, which walks on screen wherever they are on the site and says who you are and what you paid. Call it as POST /api/x402/knock?to=<username>: the challenge quotes that door's own price, and the USDC settles directly to the recipient, not to three.ws. Read GET /api/knock/door?handle=<username> for a door's exact price and limits before you pay, or GET /api/knock/directory for every open door. The response carries a receipt URL you can poll for a reply without needing an account. The price listed here is the representative one a probe with no handle receives.

Returns: three.ws Knock result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fknock.
## `POST /api/x402/llm-proxy` - $0.005

three.ws LLM Inference Proxy — pay per completion with no API key required. Runs one-shot text prompts through the platform's free-first provider chain. Response includes measured latency, token counts, and the provider actually used. Ideal for latency benchmarking, agent pipelines, and one-off completions. Model aliases: "fast" (sub-second) · "smart" (quality backstop). Price: $0.005 USDC per completion on Base or Solana.

Returns: three.ws LLM Inference Proxy result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fllm-proxy.
## `GET /api/x402/market-anomalies` - $0.001

Live market anomaly feed for agents. Pay $0.001 USDC per call. A scanner runs every 15 minutes over real series (CoinGecko hourly prices, DeFiLlama Solana TVL and stablecoin supply, stablecoin peg board, Hyperliquid funding history and open-interest snapshots) and scores each with a modified z-score, an EWMA deviation and a rate-of-change gate. Each event carries processor, subject, severity (medium, high, critical), direction, value against baseline, percent change, score and the detectors that agreed. Filter with ?processor=, ?severity= (minimum), ?subject=, ?hours= and ?limit=. Sparse or flat series are skipped, never scored.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `processor` | query | string | no | Optional: price, tvl, stablecoin_supply, stablecoin_peg, funding or open_interest. |
| `severity` | query | string | no | Minimum severity: medium (default), high or critical. |
| `subject` | query | string | no | Optional exact subject, e.g. a ticker (SOL), Solana, a stablecoin symbol or a perp (SOL-USD). |
| `hours` | query | string | no | Look-back window in hours, 1-168. Default 24. |
| `limit` | query | string | no | Max events, 1-200. Default 50. |

Returns: three.ws Market Data result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fmarket-anomalies.
## `GET /api/x402/market-categories` - $0.001

Crypto sector leaderboard for agents — pay $0.001 USDC per call. Returns every CoinGecko category (AI, layer-1, memecoins, DeFi, RWA, …) ranked by market cap, each with 24h market-cap change, 24h volume, and its top-3 coins. Feed a category id into the market-coins endpoint to drill into one sector. Same data behind three.ws/categories.

Returns: three.ws Market Data result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fmarket-categories.
## `GET /api/x402/market-chains` - $0.001

Cross-chain TVL leaderboard for agents — pay $0.001 USDC per call. Returns the top 100 blockchains ranked by DeFi TVL from DeFiLlama, each with its native token symbol and percentage share of total locked value, plus the whole-market TVL and chain count. Where the capital actually lives, one call. Same data behind three.ws/chains.

Returns: three.ws Market Data result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fmarket-chains.
## `GET /api/x402/market-chart` - $0.001

Historical price series for agents — pay $0.001 USDC per call. Pass ?id=<coingecko-id>&days=<1|7|30|90|365>. Returns a compact [[timestamp_ms, price_usd], …] array with upstream-chosen granularity (5-minutely for 1 day, hourly to 90 days, daily beyond). The coin id is supplied at runtime — the same series behind the three.ws/coin charts.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | query | string | yes | CoinGecko coin id (lowercase slug, e.g. bitcoin). |
| `days` | query | string | no | Window: 1, 7, 30, 90, or 365. Default 30. |

Returns: three.ws Market Data result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fmarket-chart.
## `GET /api/x402/market-coin` - $0.001

Rich single-coin profile for agents — pay $0.001 USDC per call. Pass ?id=<coingecko-id> (e.g. bitcoin) or ?contract=<solana-mint>. Returns live market stats (price, cap, FDV, volume, 1h→1y change windows, ATH/ATL, supply), official links, per-chain contract addresses, developer activity, community size, sentiment votes, and a sanitized plain-text description. The id or contract is supplied at runtime — generic coin-agnostic plumbing, same data behind the three.ws/coin pages.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | query | string | no | CoinGecko coin id (lowercase slug, e.g. bitcoin). Required unless contract is set. |
| `contract` | query | string | no | Solana token mint (base58) — alternative lookup key to id. |

Returns: three.ws Market Data result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fmarket-coin.
## `GET /api/x402/market-coins` - $0.001

Ranked cryptocurrency market table for agents — pay $0.001 USDC per call. Returns price, market cap, 24h volume, 24h/7d percentage change, rank, logo, and a downsampled 7-day sparkline per coin (up to 250 per page). Scope to one sector with ?category=<coingecko-category-id>, page with ?page=&per_page=, or resolve names/tickers to coin ids with ?q=<text>. CoinGecko primary with CoinLore failover — the same feed behind three.ws/coins.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `page` | query | string | no | Page number, 1–20. Default 1. |
| `per_page` | query | string | no | Rows per page, 10–250. Default 100. |
| `category` | query | string | no | Optional CoinGecko category id (e.g. artificial-intelligence) to scope the table to one sector. |
| `q` | query | string | no | Search mode: resolve a name/ticker to CoinGecko coin ids (returns top-10 matches instead of the table). |

Returns: three.ws Market Data result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fmarket-coins.
## `GET /api/x402/market-defi` - $0.001

DeFi protocol rankings for agents — pay $0.001 USDC per call. Returns the top 100 DeFi protocols by TVL from DeFiLlama with 1d/7d TVL change, deployed chains, category, token symbol, and market cap — plus whole-market total TVL and protocol count with centralized-exchange reserves excluded so the totals mean actual DeFi. Same data behind three.ws/defi.

Returns: three.ws Market Data result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fmarket-defi.
## `GET /api/x402/market-derivatives` - $0.001

Derivatives market data for agents — pay $0.001 USDC per call. Default mode returns the top 100 perpetual futures contracts by 24h volume with price, 24h change, funding rate, and open interest. Pass ?view=exchanges for the derivatives-venue leaderboard ranked by BTC open interest (perp/futures pair counts included). Same data behind three.ws/derivatives.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `view` | query | string | no | Set to 'exchanges' for the derivatives-venue leaderboard; omit for perp tickers. |

Returns: three.ws Market Data result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fmarket-derivatives.
## `GET /api/x402/market-dex-volumes` - $0.001

DEX trading-volume rankings for agents — pay $0.001 USDC per call. Returns the top 100 decentralized exchanges by 24h volume from DeFiLlama, each with 7d volume, week-over-week change, deployed chains, and its share of whole-market 24h volume — plus market totals and the aggregate daily chart. Same data behind three.ws/dex-volumes.

Returns: three.ws Market Data result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fmarket-dex-volumes.
## `GET /api/x402/market-exchanges` - $0.001

Spot exchange rankings for agents — pay $0.001 USDC per call. Returns the top 100 crypto exchanges ranked by CoinGecko trust score, each with 24h trading volume in BTC and USD (converted at the live BTC price), trust rank, country, year established, and homepage. Same data behind three.ws/exchanges.

Returns: three.ws Market Data result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fmarket-exchanges.
## `GET /api/x402/market-fees` - $0.001

Protocol fee and revenue rankings for agents — pay $0.001 USDC per call. Returns the top 100 protocols by 24h fees from DeFiLlama with 24h/7d/30d totals and momentum. Default ?type=fees is what users pay to use each protocol; ?type=revenue is the slice the protocol keeps — the closest thing on-chain to an earnings report. Includes whole-market totals and the aggregate daily chart. Same data behind three.ws/fees.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `type` | query | string | no | 'fees' (default — what users pay) or 'revenue' (what the protocol keeps). |

Returns: three.ws Market Data result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fmarket-fees.
## `GET /api/x402/market-gas` - $0.001

Live Ethereum gas oracle for agents — pay $0.001 USDC per call. Computes slow/standard/fast tiers from eth_feeHistory over the last ~20 blocks (base fee + 25th/50th/90th priority-fee percentiles, median-smoothed) across failover public RPCs — no third-party gas API. Each tier carries USD cost estimates for an ETH transfer, token transfer, DEX swap, and NFT mint at the live ETH price. Same oracle behind three.ws/gas.

Returns: three.ws Market Data result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fmarket-gas.
## `GET /api/x402/market-global` - $0.001

Global crypto market snapshot for agents — pay $0.001 USDC per call. Returns total market cap, 24h volume, top-2 dominance shares, active coin count (CoinGecko → CoinPaprika → CoinLore failover), and the alternative.me Fear & Greed index with its label. The one-call market-regime check. Same data behind the three.ws/coins stats bar and /fear-greed.

Returns: three.ws Market Data result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fmarket-global.
## `GET /api/x402/market-hacks` - $0.001

DeFi exploit database for agents — pay $0.001 USDC per call. Returns DeFiLlama's full hack history newest-first: amount stolen in USD, attack technique and classification, affected chains, bridge-hack flag, target type, post-mortem link, and funds returned. Search with ?search=<text> over name/technique/classification, page with limit/offset. Headline stats cover all-time and trailing-12-month losses and the bridge-hack share. Same data behind three.ws/hacks.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `search` | query | string | no | Case-insensitive match over incident name, technique, and classification. |
| `limit` | query | string | no | Rows per page, 1–200. Default 100. |
| `offset` | query | string | no | Pagination offset. Default 0. |

Returns: three.ws Market Data result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fmarket-hacks.
## `GET /api/x402/market-heatmap` - $0.002

three.ws Market Heatmap — pay $0.002 USDC per call for a normalized snapshot of the top coins by market cap: rank, price, 1 h / 24 h / 7 d momentum, market cap, and 24 h volume per coin, plus market-breadth statistics (advancers vs decliners, average and median 24 h move) that tell an agent whether strength is broad or narrow. Dual live sources with automatic failover (CoinGecko primary, CoinPaprika fallback) so a single upstream rate-limit never breaks a paid call. Size the board with ?limit=1..100. Refreshed every 60 seconds; upstream outages refuse before settlement.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `limit` | query | integer | no | Coins to return, largest market cap first. |

Returns: three.ws Market Heatmap result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fmarket-heatmap.
## `GET /api/x402/market-mood` - $0.002

three.ws Market Mood Index — pay $0.002 USDC per call for a composite market-mood reading no single index gives you. Blends the Crypto Fear & Greed index (with its 24 h delta) with live lexicon sentiment scored across the newest headlines from 192 crypto publisher feeds into one 0–100 mood score and label, and returns both components so you can see when positioning (Fear & Greed) and narrative (news tone) disagree — the divergence signal. Includes the bullish and bearish headlines currently driving the news component, with links, plus a best-effort volatility read: Deribit DVOL implied-volatility index values for BTC and ETH with their 24 h change (null if Deribit is unreachable; volatility never gates the call). Both mood components must be live or the call refuses before settlement.

Returns: three.ws Market Mood result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fmarket-mood.
## `GET /api/x402/market-pulse` - $0.005

The flagship one-call market bundle for agents — pay $0.005 USDC for what would take eight separate calls: global market cap/volume/dominance, the Fear & Greed index, the top-10 coins with 24h/7d change, trending searches, the live ETH gas standard tier, DeFi total TVL with the top-10 protocols, total stablecoin supply, whole-market 24h DEX volume, and 24h protocol fees. Sections degrade independently — one upstream hiccup nulls its section instead of failing the call. The cheapest complete market context an agent can buy.

Returns: three.ws Market Data result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fmarket-pulse.
## `GET /api/x402/market-stablecoins` - $0.001

Stablecoin market monitor for agents — pay $0.001 USDC per call. Returns the top 100 pegged assets by on-chain circulating supply from DeFiLlama, each with live price (peg-health check), peg type and mechanism, and the chains it lives on — plus the total stablecoin market cap across every tracked asset. Same data behind three.ws/stablecoins.

Returns: three.ws Market Data result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fmarket-stablecoins.
## `GET /api/x402/market-trending` - $0.001

Trending crypto assets for agents — pay $0.001 USDC per call. Returns the most-searched coins on CoinGecko over the last 24 hours (with price, 24h change, market cap, and trending rank), the trending categories, and the trending NFT collections (floor price and 24h floor change). Attention flows before price — this is the early signal. Same data behind three.ws/markets/trending.

Returns: three.ws Market Data result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fmarket-trending.
## `GET /api/x402/market-yields` - $0.001

DeFi yield-pool explorer for agents — pay $0.001 USDC per call. Queries ~15,000 pools from DeFiLlama: filter with ?chain=&project=&stablecoin=&search=&minTvl=, sort by tvl or apy (APY sort is dust-guarded to pools ≥ $10k TVL so fake five-digit APYs never outrank real venues), page with limit/offset. Each pool carries APY split (base/reward), 30-day mean, IL risk, exposure, and predicted outlook. Pass ?pool=<uuid> for one pool's APY/TVL history. Same engine behind three.ws/yields.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `chain` | query | string | no | Filter to one chain (case-insensitive, e.g. solana). |
| `project` | query | string | no | Filter to one protocol slug (e.g. aave-v3). |
| `stablecoin` | query | string | no | 'true' for stablecoin pools only, 'false' to exclude them. |
| `search` | query | string | no | Substring match over symbol, project, and chain. |
| `minTvl` | query | string | no | Minimum pool TVL in USD. |
| `sort` | query | string | no | 'tvl' (default) or 'apy' (dust-guarded to pools ≥ $10k TVL). |
| `limit` | query | string | no | Rows per page, 1–200. Default 100. |
| `offset` | query | string | no | Pagination offset. Default 0. |
| `pool` | query | string | no | Chart mode: a DeFiLlama pool uuid — returns that pool's APY/TVL history instead of the list. |

Returns: three.ws Market Data result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fmarket-yields.
## `POST /api/x402/mcp-tool-catalog` - $0.001

three.ws MCP Tool Discovery — pay $0.001 USDC to discover MCP tools that were registered (or whose price/shape changed, or that were removed) on the three.ws MCP server since you last probed. Returns the diff against a durable tool registry so agents can feature-flag new capabilities the moment they ship instead of re-fetching and diffing tools/list themselves.

Returns: three.ws MCP Tool Discovery result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fmcp-tool-catalog.
## `GET /api/x402/mint-to-mesh` - $0.001

Pay $0.001 USDC to resolve a Solana fungible-token mint to a binary glTF (GLB) cube themed for that token. Color is hashed from the mint; the Metaplex JSON image, when present, is embedded as a baseColor texture.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `mint` | query | string | yes | Base58 SPL mint address on Solana mainnet. |

Returns: Themed GLB JSON envelope.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fmint-to-mesh.
## `POST /api/x402/mint-to-mesh-batch` - $0.05

Pay $0.05 USDC to resolve 1–10 Solana SPL mints to themed binary glTF cubes in a single call. Per-mint failures report ok:false instead of failing the whole batch.

Returns: Batch mesh JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fmint-to-mesh-batch.
## `GET /api/x402/model-check` - $0.001

Pay $0.001 USDC to fetch a glTF/GLB model from a URL and return structural stats (vertex/triangle counts, materials, textures, animations, extensions) plus a prioritized list of optimization recommendations.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `url` | query | string | yes | Public HTTPS URL of a glTF/GLB model. |

Returns: Inspection + recommendation JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fmodel-check.
## `POST /api/x402/model-validation-sweep` - $0.001

three.ws model quality sweep — picks the next public GLB avatar in the database that has never been inspected (or whose inspection is older than 24 hours), downloads the file, runs the glTF-Transform inspector, computes a 0-100 quality score, and records a time-series row. Use to proactively detect geometry errors, missing rigs, and unsupported features before users encounter them in the viewer.

Returns: three.ws Model Validation Sweep result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fmodel-validation-sweep.
## `GET /api/x402/news-pulse` - $0.002

three.ws Ticker News Pulse — pay $0.002 USDC per call to measure how loudly the news cycle is talking about one ticker right now. Scans the live output of 192 crypto publisher feeds (the same engine behind the free three.ws news API) for mentions of your ticker inside a 1–72 h window and returns the mention count, unique outlets covering it, the sentiment split with an aggregate score, coverage velocity versus the immediately preceding window (accelerating / steady / cooling), and the top headlines with links. Zero mentions is a truthful, billable answer — silence is a signal. Feed outages refuse before settlement.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `ticker` | query | string | yes | Ticker symbol to scan for, e.g. BTC. $-prefix optional. |
| `hours` | query | integer | no | Look-back window in hours. |

Returns: three.ws News Pulse result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fnews-pulse.
## `GET /api/x402/news-wire-pulse` - $0.002

three.ws Global News Wire Pulse: pay $0.002 USDC per call to get only the GDELT articles that have appeared for your query since a cursor you supply, plus a fresh cursor for the next poll. Built for agents running a repeated poll loop against Global News Wire Search without re-fetching the same articles. Start with News Wire Search to get a query working, then switch to Pulse for ongoing monitoring.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `q` | query | string | yes | Search query, same syntax as News Wire Search. |
| `cursor` | query | string | yes | GDELT timestamp (YYYYMMDDHHMMSS) or ISO-8601 timestamp to poll since. |
| `maxRecords` | query | integer | no |  |

Returns: three.ws News Wire result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fnews-wire-pulse.
## `POST /api/x402/node-inference` - $0.005

Run one inference job on the open three.ws node network. The platform enqueues the job for a live community node, verifies the node's ed25519 receipt against its own record of the job, and settles only for a verified result. Capabilities: text-embedding ($0.001 USDC) and text-generation ($0.005 USDC). No live node for the capability answers 503 and settles nothing.

Returns: three.ws Node Network Inference result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fnode-inference.
## `POST /api/x402/notify` - $0.001

Notification Delivery Probe — pay $0.001 USDC to send a canary message through the platform notification channel and confirm delivery. Returns { delivered, channel, latency_ms } so the autonomous loop can assert the notification subsystem is alive within a 2-second SLA. Channel "canary" is the x402 loop heartbeat lane; "ops" and "system" route to the ops alert surface.

Returns: three.ws Notification Delivery result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fnotify.
## `GET /api/x402/onchain-identity-verify` - $0.005

Pay $0.005 USDC to verify whether a three.ws agent_id actually owns/deployed a given contract or mint on a given CAIP-2 chain, using the canonical meta.onchain unified index.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `agent_id` | query | string | yes |  |
| `chain` | query | string | yes |  |
| `contract_or_mint` | query | string | yes |  |

Returns: Verification result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fonchain-identity-verify.
## `POST /api/x402/pay-by-name` - $0.001

Pay-By-Name Resolution — pay $0.001 USDC to resolve a wallet name (@username, a *.sol name, or a raw base58 address) to a verified on-chain Solana address via the three.ws pay-by-name registry. Returns the resolved address, an on-curve verification flag, and the resolution source.

Returns: Pay-By-Name Resolution result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fpay-by-name.
## `GET /api/x402/permit2-paid-demo` - $0.001

Pay $0.001 USDC via the Permit2-only path so a wallet holding USDC but zero ETH can complete the flow. CDP's x402ExactPermit2Proxy submits the EIP-2612 permit + Permit2 transfer atomically; the response surfaces the on-chain tx hash and a Basescan link.

Returns: Settlement summary with tx hash.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fpermit2-paid-demo.
## `POST /api/x402/pipeline` - $0.15

One call, full 3D asset pipeline — text or GLB in, rigged/optimized game-ready GLB out; the only asset pipeline in the x402 ecosystem. Submit an ordered chain of stages (generate → rig → remesh → gameready → stylize) and get back a job token you poll for FREE at GET /api/forge?job=<id>, watching per-stage progress until the final GLB is delivered. Priced per stage and quoted EXACTLY in the 402 challenge (the sum of the requested stages). Pay autonomously in USDC on Solana mainnet — no API key, no account.

Returns: three.ws 3D Asset Pipeline result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fpipeline.
## `POST /api/x402/pipeline-gameready` - $0.03

3D Asset Pipeline — Game-Ready: pay $0.03 USDC to make a GLB engine-ready. The mesh is retopologized to a fixed polygon budget (quad QuadriFlow or silhouette-preserving low-poly) with PBR re-baked onto the new topology. POST a public glb_url + poly_budget; get back a durable first-party GLB URL.

Returns: three.ws Pipeline - Game-Ready result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fpipeline-gameready.
## `POST /api/x402/pipeline-rembg` - $0.01

3D Asset Pipeline — Background Removal: pay $0.01 USDC to strip the background from an image, returning a transparent PNG — the clean reference view image→3D reconstruction needs so it never bakes a room into the mesh. POST a public image_url; get back a durable first-party PNG URL.

Returns: three.ws Pipeline - RemBG result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fpipeline-rembg.
## `POST /api/x402/pipeline-remesh` - $0.03

3D Asset Pipeline — Remesh: pay $0.03 USDC to retopologize a GLB. Triangle, quad, or low-poly remeshing plus repair and decimation to a target face count, with the texture re-baked onto the new topology. POST a public glb_url and options; get back a durable first-party GLB URL.

Returns: three.ws Pipeline - Remesh result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fpipeline-remesh.
## `POST /api/x402/pipeline-rig` - $0.05

3D Asset Pipeline — Rig: pay $0.05 USDC to make a static GLB animation-ready. A humanoid skeleton is inferred and bound to the mesh with skin weights so the model can walk, wave, and emote. POST a public glb_url; get back a durable first-party rigged GLB URL. No other x402 resource rigs a mesh.

Returns: three.ws Pipeline - Rig result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fpipeline-rig.
## `POST /api/x402/pipeline-stylize` - $0.03

3D Asset Pipeline — Stylize: pay $0.03 USDC to geometrically restyle a GLB. Voxel, brick, Voronoi-shatter, or faceted low-poly filters that rebuild the mesh itself (not a shader), so the look survives export to any engine. POST a public glb_url + style; get back a durable first-party GLB URL.

Returns: three.ws Pipeline - Stylize result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fpipeline-stylize.
## `GET /api/x402/places-detail` - $0.002

three.ws Place Detail: pay $0.002 USDC per call to fetch the full live OpenStreetMap record for one place, by the id returned from Places Search (e.g. "node-1072800838"). Returns every OSM tag alongside the structured fields (name, category, coordinates, opening hours, contact, address, cuisine).

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | query | string | yes | Place id from Places Search, e.g. "node-1072800838", "way-55", "relation-9". |

Returns: three.ws Places result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fplaces-detail.
## `POST /api/x402/print-order` - $12.00

Order a real, physical 3D print of any model and have it manufactured and shipped to a street address, paying in USDC. Quote first at POST /api/print/quote (free, keyless) with a creationId or a glbUrl, a materialId from GET /api/print/catalog, a target height in millimetres and an ISO country code; that returns a printability report, an itemized price and a signed quote token. Post the token plus a shipping address here and the 402 challenge quotes that quote's exact total, so the price shown is the price of that object at that size to that country. Settling it opens a real manufacturing job: safety screening, production, tracked shipping, and a certificate of authenticity attested on Solana. Track it at GET /api/print/orders/{id}. The 12 USDC listed here is the catalog floor, not a list price.

Returns: three.ws Materialize result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fprint-order.
## `GET /api/x402/pump-agent-audit` - $0.02

Pay $0.02 USDC to retrieve a full operational audit of a pump.fun mint: USDC paid in, distinct payers, distribute/buyback success history, latest error reasons, and derived risk flags.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `mint` | query | string | yes |  |

Returns: Audit JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fpump-agent-audit.
## `POST /api/x402/pump-launch` - $5.00

Pay $5.00 USDC to deploy a brand-new pump.fun token. Supply name + symbol and either a pre-pinned metadataUri or an imageUrl (the server pins the image + descriptor to pump.fun IPFS). The server fronts the SOL deploy cost and signs the create-coin tx, so the buyer needs no SOL and no account. Creator rewards accrue to any Solana wallet you nominate; an optional vanity prefix/suffix grinds a custom mint address. Returns mint + tx signature + pump.fun URL.

Returns: Deploy result: mint, tx signature, pump.fun URL.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fpump-launch.
## `POST /api/x402/rate-limit-probe` - $0.001

Rate-Limit Capacity Probe — pay $0.001 USDC to learn how many more calls the x402 autonomous loop can make to a target endpoint today before hitting its daily USDC spend cap. Returns remaining_calls, reset_at, and cooldown_active so agents can throttle dynamically instead of discovering the cap by failure.

Returns: three.ws Rate-Limit Probe result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Frate-limit-probe.
## `POST /api/x402/remix-asset` - $0.25

Remix a published, remixable 3D model: pay a fixed fee in USDC and describe the change in words ("make it metallic", "add wings"). The platform generates a NEW model anchored to the source, records durable parent→child provenance, and routes a creator-set royalty (≤20% of the fee, the remixer always keeps the majority) on-chain to the original creator. Browse remixable assets and their royalty terms for free at GET /api/remix-feed; publish your own finished models there to earn royalties when others build on them.

Returns: Remix a 3D asset + royalties result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fremix-asset.
## `POST /api/x402/research-bibliography` - $0.005

three.ws Bibliography: pay $0.005 USDC per call to get formatted BibTeX and/or APA 7 citation entries for up to 25 DOIs in one request, sourced live from Crossref.

Returns: three.ws Research result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fresearch-bibliography.
## `GET /api/x402/research-paper` - $0.003

three.ws Paper Detail: pay $0.003 USDC per call for a single paper's full metadata (title, abstract, TL;DR, year, venue, authors, fields of study, open-access PDF link) plus a two-sided citation graph (top citations and references) from Semantic Scholar, keyed by DOI, arXiv id, or Semantic Scholar id. Falls back to Crossref metadata (marked partial, no citation graph) when Semantic Scholar is unreachable for a DOI.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | query | string | yes | A DOI, arXiv id (e.g. "1706.03762"), or Semantic Scholar paper id. |

Returns: three.ws Research result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fresearch-paper.
## `GET /api/x402/robinhood-portfolio` - $0.002

Robinhood Chain Portfolio — every Stock Token a wallet holds on Robinhood Chain (4663), with the true position (raw ERC-20 balance × ERC-8056 uiMultiplier — ignoring the multiplier misstates value after a split or dividend) and current USD value from the on-chain Chainlink NAV feed for each symbol. Returns per-position shares, NAV price, and USD value, plus a total portfolio value. Zero balances are omitted.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `address` | query | string | yes | EVM wallet address to value (0x…40 hex chars). |

Returns: Robinhood Chain Portfolio result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Frobinhood-portfolio.
## `POST /api/x402/schema-check` - $0.001

three.ws JSON API schema conformance checker — pay $0.001 USDC to fetch a named three.ws public API and validate its response against the declared schema. Surfaces breaking schema changes before users notice a broken feed. Current target: changelog_json — the /changelog.json feed holders and RSS consumers depend on. Returns { valid, version, entry_count, schema_errors }.

Returns: three.ws JSON API Schema Check result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fschema-check.
## `GET /api/x402/skill-call` - $0.001

Pay the per-call price of a marketplace skill in USDC (Base or Solana) and receive its executable payload: the tool schema and content the calling agent runs. Payment settles straight to the skill author's wallet. Per-call pricing — every invocation is a fresh payment.

Price varies by request from $0.001 up to $10.00 USD; the heading above shows the floor.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `skill` | query | string | yes | Unique skill slug from the marketplace_skills catalog. |

Returns: Skill payload: tool schema + content.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fskill-call.
## `GET /api/x402/skill-marketplace` - $0.001

Pay $0.001 USDC to list active skill listings with prices across all three.ws agents. Optional skill filter returns the cheapest provider for that capability.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `skill` | query | string | no |  |
| `limit` | query | integer | no |  |

Returns: Marketplace listings JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fskill-marketplace.
## `GET /api/x402/solana-register-health` - $0.001

Solana Agent Registration Health Check — verifies three.ws's server-custodial Solana agent-registration subsystem end-to-end by resolving a known canary agent's on-chain Metaplex Agent Registry record (Identity PDA + Core asset) and confirming both accounts exist on-chain right now. Returns a health snapshot with latency and the checked asset. Pay-per-call in USDC on Solana or Base mainnet.

Returns: three.ws Solana Reg Health result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fsolana-register-health.
## `POST /api/x402/spend-session` - $0.01

three.ws Spend Session Health — pay $0.01 USDC to probe the Agent Payment Sessions governance layer. mode:"canary" creates a canary session row and immediately consumes it, returning { created, consumed, latency_ms } — the most important health check for the x402 governance layer. mode:"audit" returns a live aggregate snapshot of all payment sessions (active count, remaining budget, expired_count_24h). Pay-per-call in USDC on Solana mainnet.

Returns: three.ws Spend Session Health result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fspend-session.
## `GET /api/x402/stablecoin-health` - $0.005

three.ws Stablecoin Peg Monitor — pay $0.005 USDC per call for a live health report on the stablecoin market. Every USD-pegged asset is scored on current peg deviation in basis points with an on-peg / drifting / depegged verdict (25 bps and 100 bps thresholds), circulating supply, and 24 h / 7 d / 30 d supply change — the flow signal that front-runs visible depegs. Includes market-wide totals and a depeg alert list. Filter one coin with ?symbol= or size the board with ?limit=. Live DeFiLlama stablecoins data, refreshed every 5 minutes; unavailable data refuses before settlement.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `symbol` | query | string | no | Return only this stablecoin symbol, e.g. USDC (case-insensitive). |
| `limit` | query | integer | no | Coins to return, largest supply first. |

Returns: three.ws Stablecoin Monitor result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fstablecoin-health.
## `GET /api/x402/symbol-availability` - $0.001

Pay $0.001 USDC to check whether a candidate ticker collides with any three.ws-indexed pump.fun mint. Returns exact matches plus trigram-similar tickers and a recommendation.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `ticker` | query | string | yes |  |
| `network` | query | string | no |  |

Returns: Symbol availability JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fsymbol-availability.
## `POST /api/x402/telegram-health` - $0.001

Changelog Telegram Bot Health Check — pays $0.001 USDC to verify that the three.ws platform bot can reach the Telegram API and is alive. Returns { reachable, bot_id, bot_username, latency_ms }. If unreachable, new changelog entries will not reach $THREE holders until the bot is restored.

Returns: three.ws Telegram Bot Health result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Ftelegram-health.
## `GET /api/x402/three-intel` - $0.01

Pay $0.01 USDC for live $THREE market intel: price, 24 h change, market cap, liquidity, 24 h volume, and a bullish / bearish / neutral signal with a two-sentence rationale. Powered by live DexScreener data — the same oracle behind the paid intel kiosk in the $THREE town on three.ws/play.

Returns: $THREE market intel JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fthree-intel.
## `GET /api/x402/token-intel` - $0.01

three.ws Token Oracle — pay $0.01 USDC per call for live market intel on ANY token by contract address: price, 24 h change, market cap, liquidity, 24 h volume, and a bullish / bearish / neutral signal with a two-sentence rationale. Pass ?mint=<contract-address> (Solana mint or EVM 0x). The mint is supplied at runtime — generic coin-agnostic plumbing. Powered by live DexScreener data; this is the paid endpoint the CA-to-x402 resolver generates.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `mint` | query | string | yes | Token contract address — Solana base58 mint or EVM 0x address. |

Returns: three.ws Token Oracle result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Ftoken-intel.
## `GET /api/x402/transit-delays` - $0.001

three.ws Transit Delay Snapshot: pay $0.001 USDC per call to see how the MBTA's realtime feed compares to the scheduled timetable right now at a stop, optionally filtered to one route. delaySeconds is the realtime prediction minus the scheduled time for the same trip, measured from the feed, never modelled. Returns a per-arrival breakdown plus a summary (on-time / late / early counts, median and worst delay, and a verdict). Find a stop id with Transit Trip Plan or by name first.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `stop` | query | string | yes | Stop id, station name, or "lat,lon". |
| `route` | query | string | no | Optional feed route id to filter by. |
| `limit` | query | integer | no |  |

Returns: three.ws Transit result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Ftransit-delays.
## `POST /api/x402/tutor` - $0.01

Pay $0.01 USDC per answered question. Returns a leveled explanation, key points, a worked example, and a follow-up, plus a running session tab so the UI can render a live itemized invoice. Pass a sessionId to accumulate a tab across questions.

Returns: Answer JSON with running session tab.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Ftutor.
## `GET /api/x402/vanity` - $0.01

Pay to generate a brand-new Solana keypair whose Base58 address starts with a chosen prefix and/or ends with a chosen suffix. Returns the public address and its secret key (Base58 + 64-byte array) so it imports into any Solana wallet. Ground fresh per request in a Rust/WASM ed25519 engine and never stored. Difficulty-tiered price ($0.01 for 1 char, $0.05 for 2, $0.25 for 3); combined pattern capped at 3 Base58 characters. Settlement runs only after a successful grind, so an exhausted budget costs nothing.

Price varies by request from $0.01 up to $0.25 USD; the heading above shows the floor.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `prefix` | query | string | no | Base58 characters the address must start with (excludes 0, O, I, l). Combined with suffix, max 3. Provide prefix and/or suffix. |
| `suffix` | query | string | no | Base58 characters the address must end with. Combined with prefix, max 3. |
| `ignoreCase` | query | string | no | When 1/true, match case-insensitively (faster, less specific). |

Returns: Keypair JSON: address + secret key.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fvanity.
## `GET /api/x402/vanity-premium` - $1.00

Premium Vanity Inventory — buy a PRE-GROUND Solana address with a long (4–5+ char) brandable prefix, delivered instantly from stock. Browse available patterns and prices with a plain GET; buy one with GET ?address=<base58> via x402 (USDC on Base or Solana). Price scales with grind difficulty ($1–$50). The key is delivered exactly ONCE and its stored ciphertext is destroyed on delivery (delete-after-reveal). Optional sealTo=<X25519 public key> seals the key to you so plaintext never appears in the response. CUSTODY: keys are platform-generated — use one as a token MINT address or sweep assets to self-generated custody, not as a long-term treasury. Distinct from the live /api/x402/vanity grinder (fresh <=3-char keypair per request) — this tier sells rarer addresses too slow to grind on demand.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `address` | query | string | no | A Base58 address from the premium inventory listing (GET with no address to browse). Buys that exact pre-ground address. |
| `sealTo` | query | string | no | Optional. Your 32-byte X25519 public key (Base58/Base64url/hex) to receive the key ECIES-sealed — plaintext never appears in the response. |

Returns: three.ws Premium Vanity result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fvanity-premium.
## `GET /api/x402/vanity-verifiable` - $0.02

Grind a fresh Solana keypair whose Base58 address matches a chosen prefix/suffix, with a commit–reveal receipt signed by the service key (published at /.well-known/three-vanity.json) so the buyer can prove the key was ground fresh and never kept. Pass sealTo=<X25519 pubkey> to ECIES-seal the secret. Difficulty-tiered $0.02–$0.40; combined pattern ≤3 Base58 chars; settlement runs only after a successful grind.

Price varies by request from $0.02 up to $0.40 USD; the heading above shows the floor.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `prefix` | query | string | no | Base58 prefix the address must start with (excludes 0,O,I,l). |
| `suffix` | query | string | no | Base58 suffix the address must end with. Combined with prefix ≤3. |
| `sealTo` | query | string | no | Recommended. Your X25519 public key; when set the secret is sealed to it and omitted from the response. |

Returns: Keypair + signed grind receipt JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fvanity-verifiable.
## `POST /api/x402/wallet-connect` - $0.001

Wallet Connection Session Health Check — probes the SIWS (Sign-In With Solana) session initiation path: issues a real nonce challenge against the platform auth gateway, validates its structure and expiry, and measures roundtrip latency. Returns { session_created, latency_ms }. Pay-per-call in USDC on Solana or Base mainnet.

Returns: three.ws Wallet Connect Health result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fwallet-connect.
## `GET /api/x402/weather-guard-decision` - $0.002

three.ws Weather Guard decision: pay $0.002 USDC per call to turn the next 6 hours of live forecast at any lat/lon into a go / caution / no-go verdict for a named activity. Each activity (running, cycling, outdoor-event, drone-flight, photography) carries its own wind, precipitation and weather-code thresholds; the response lists every reason a threshold was crossed, the live forecast window it judged, and any active NWS severe-weather alert that forced a no-go. Same live Open-Meteo/NWS sourcing as weather-guard-forecast.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `lat` | query | number | yes | Latitude. |
| `lon` | query | number | yes | Longitude. |
| `activity` | query | string | yes |  |

Returns: three.ws Weather Guard result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fweather-guard-decision.
## `GET /api/x402/yield-scan` - $0.005

three.ws Yield Scanner — pay $0.005 USDC per call to screen 15,000+ live DeFi yield pools in one request. Filter by chain, minimum TVL, and stablecoin-only exposure; sort by APY or TVL. Every returned pool carries the full APY breakdown (base vs reward, 30-day mean), pool TVL, and derived risk flags: impermanent-loss exposure, APY volatility (sigma), an apy-spike flag when the current rate runs far above its 30-day mean, and the upstream outlier marker. Live DeFiLlama yields data, refreshed every 10 minutes. Unavailable data refuses before settlement — no charge for an empty scan.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `chain` | query | string | no | Filter to one chain, e.g. Ethereum, Solana, Base (case-insensitive). |
| `stable` | query | boolean | no | true → stablecoin-denominated pools only. |
| `minTvlUsd` | query | number | no | Minimum pool TVL in USD. |
| `sort` | query | string | no | Ranking dimension. |
| `limit` | query | integer | no | Pools to return. |

Returns: three.ws Yield Scanner result JSON.

Full request/response schema: https://three.ws/openapi.json#/paths/%2Fapi%2Fx402%2Fyield-scan.
## Errors

| Status | Meaning |
| --- | --- |
| 400 | Missing or invalid request parameters. |
| 402 | Payment required: pay one of the accepts[] rails above and retry with an X-PAYMENT header. |
| 404 | Unknown resource or record. |
| 429 | Rate limited; back off and retry. |
| 500 | Upstream or internal failure; safe to retry. |

## Data source

Every endpoint above calls a live production handler: real model-generation pipelines, real on-chain data, real database records. None of it is a fixture, a cache-only demo, or a stub response; a payment always buys a real computation or a real query.