Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

17.2 KB
Raw Blame

CA to x402

Paste a token contract address, get back a live, agent-payable x402 market-intel endpoint for that exact token. The generated endpoint costs a small USDC payment per call, is discoverable in the x402 bazaar, and needs no keys, no backend, and no deploy from the person who generated it.

The tool lives at /ca2x402.

Source: page pages/ca2x402.html, frontend src/ca2x402.js, free resolver api/ca2x402/resolve.js, the paid service it generates api/x402/token-intel.js, market reader and signal/risk math api/_lib/token-market.js, pricing api/_lib/x402-prices.js, storefront listing api/_lib/service-catalog/services/token-intel.js.

This is generic, coin-agnostic plumbing: the mint is an input supplied at runtime by whoever calls it. Every example below uses <MINT_ADDRESS> as a stand-in for the address you paste. The page ships one example chip, $THREE, because $THREE is the only coin three.ws promotes; the tool itself accepts any address.


What the page does

Three steps, all real:

  1. Paste. Any Solana base58 mint or EVM 0x contract address. The input is shape-checked in the browser before a request is made (/^[1-9A-HJ-NP-Za-km-z]{32,44}$/ or /^0x[a-fA-F0-9]{40}$/).
  2. Resolve. GET /api/ca2x402/resolve pulls the token's live market from DexScreener (backed by a last-known-good copy, see below) and returns both the token preview and the generated service descriptor. This read is free and unauthenticated.
  3. Ship. The page renders the endpoint URL, its price and networks, three copy-paste snippets, and a button that fetches the real 402 Payment Required challenge from the live endpoint so you can see exactly what a buyer settles against.

The resolved address is mirrored into the URL as ?ca=<MINT_ADDRESS> (history.replaceState), so a resolved token is a shareable, reload-safe link. On boot the page reads that parameter and resolves it automatically.


The resolve flow

GET /api/ca2x402/resolve?mint=<MINT_ADDRESS>

Free, GET/OPTIONS only, CORS open to any origin, and rate-limited per client IP through the shared public read limiter (limits.publicIp in api/_lib/rate-limit.js).

What happens, in order:

  1. Validate. A missing mint is 400 missing_mint. An address that is neither a valid Solana mint nor a valid EVM address is 422 invalid_mint.
  2. Fetch the market. fetchTokenMarket() calls the public DexScreener token endpoint (no key) through the shared upstream fetcher (6 second timeout, two attempts, circuit breaker) and remembers the last payload it got for each address for 15 minutes, so a throttled indexer serves a few-minutes-old market rather than nothing. It then picks the pair with the deepest USD liquidity across every chain and DEX DexScreener knows for that address. The address may sit on either side of the pair; the reader selects whichever side matches what you passed.
  3. No market found. A well-formed address with no live pair (unlaunched, dead liquidity, or wrong chain) returns 404 { ok: false, error: 'token_not_found' } with cache-control: no-store. The page renders that as a designed empty state. Nothing is fabricated to fill the gap.
  4. Indexer unreachable. The resolver asks fetchTokenMarketResult(), which tells "no market exists" apart from "the indexer could not be reached". When DexScreener is down and this instance holds no remembered payload for the address, the answer is 503 { ok: false, error: 'market_unavailable', retry_after: 15 } with a Retry-After: 15 header and cache-control: no-store, never a 404 that would tell someone their real token does not exist. The page shows the error description with its retry button.
  5. Success. 200 { ok: true, token, service } with cache-control: public, max-age=20, stale-while-revalidate=60.

The token block

The live preview, so a user sees what was found before anyone pays:

Field Meaning
mint The resolved token address as DexScreener reports it.
symbol, name, image Identity from the pair's token metadata.
chain, dex, pair_url Where the deepest pair lives, plus its public pair page.
price_usd, change_24h Spot price and 24 hour price change (percent).
market_cap_usd, liquidity_usd, volume_24h_usd Cap (falling back to FDV), pooled depth, 24 hour volume.
momentum Price change per window: m5, h1, h6, h24.
signal, headline, rationale, confidence The derived market call (see below). null when the upstream has no 24 hour change.
risk The due-diligence score block (see below).

How the signal is derived (buildTokenSignal()), keyed on 24 hour change:

24 hour change signal Headline shape
above +5% bullish surges, strong momentum
+1% to +5% bullish climbs, moderate upside
-1% to +1% neutral flat, consolidating at the spot price
-5% to -1% bearish slips, mild weakness
below -5% bearish drops, sellers in control

The rationale adds three clauses when the data supports them: turnover (24 hour volume divided by liquidity: above 3 reads as hot, above 1 as healthy, otherwise light), order-flow skew (a buy or sell share above 60% of 24 hour transactions reads as one side dominating, otherwise two-sided), and acceleration (the last hour confirming, cooling, or bouncing against the 24 hour trend). Confidence is min(0.93, 0.64 + min(|change| / 20, 0.29)), so it rises with the size of the move and is capped.

How risk is scored (buildTokenRisk()). Higher means more risk, 0 is clean and 100 is critical. Four factors add points:

Factor Bands and points
Liquidity under $5k: +40 critical. Under $25k: +26 high. Under $100k: +12 medium. Otherwise low. Unknown: +18.
Age under 1 day: +22 high. Under 7 days: +10 medium. Otherwise low. Unknown: no points.
Float cap over 100x liquidity: +16 high. Over 30x: +7 medium. Otherwise low. Skipped when cap or liquidity is missing.
Flow sells over 62% of 24 hour transactions: +12 high. Buys over 60%: low. Otherwise medium.

The total is clamped to 0 to 100 and bucketed: critical at 70 or above, high at 45, medium at 22, otherwise low. A missing input degrades to an honest unknown factor rather than a silent pass.

The service block

The generated x402 service for that exact token:

Field Value
name three.ws Token Oracle
endpoint <APP_ORIGIN>/api/x402/token-intel?mint=<MINT_ADDRESS>
method GET
price_atomics / price_usd USDC atomics from priceFor('token-intel', '10000'), plus the same value divided by 1e6. Default is 10000 atomics, which is $0.01.
asset USDC
networks ['solana', 'base'], Solana first
pay_to { solana, base } from X402_PAY_TO_SOLANA / X402_PAY_TO_BASE (null when unset)
description The storefront listing copy, imported from the service catalog descriptor
output_schema The endpoint's JSON Schema for its response
example_output The catalog example, with mint and symbol swapped to the resolved token
bazaar_discoverable true
snippets { curl, node, agent }, see below

The endpoint origin is always env.APP_ORIGIN (set from PUBLIC_APP_ORIGIN, defaulting to https://three.ws). It is deliberately NOT derived from the request's host / x-forwarded-host headers: those are caller-controlled, and everything downstream of this URL is a payment instruction, so a spoofed host would hand the buyer an attacker-owned 402 challenge to settle against. Because the 200 is CDN-cacheable, a poisoned copy could then be served on to other visitors. Same reasoning as resolveResourceUrl() in api/_lib/x402-spec.js. A local dev resolve therefore generates the production endpoint URL, which is the one a buyer actually settles against.

Operators can retune the price at deploy time with X402_PRICE_TOKEN_INTEL=<atomics>; a non-integer value logs a warning and falls back to the default. See x402 paid endpoints for the full price-override scheme.


What the generated endpoint serves

GET /api/x402/token-intel?mint=<MINT_ADDRESS>

A standard three.ws paid endpoint built on the shared handler (api/_lib/x402-paid-endpoint.js): no X-PAYMENT header gets a 402 challenge carrying the accepted networks, asset, price, and pay-to address; the buyer retries with a signed payment and receives the intel. Settlement is recorded like any other endpoint payment (see Financial controls).

The paid response body is the token block computed fresh at call time:

{
  "mint": "<MINT_ADDRESS>",
  "symbol": "TOKEN",
  "name": "Token",
  "chain": "solana",
  "price_usd": 0.0123,
  "change_24h": 4.2,
  "market_cap_usd": 12300000,
  "liquidity_usd": 410000,
  "volume_24h_usd": 890000,
  "momentum": { "m5": 0.2, "h1": 1.1, "h6": 3.4, "h24": 4.2 },
  "signal": "bullish",
  "headline": "TOKEN climbs +4.20%, moderate upside",
  "rationale": "TOKEN is up +4.20% over 24 h, trading at $0.012300. Volume is healthy against liquidity; participation is real.",
  "confidence": 0.85,
  "risk": {
    "score": 12,
    "level": "low",
    "summary": "TOKEN clears the basic depth, age, and flow checks.",
    "factors": [
      { "label": "Liquidity", "status": "low", "detail": "$410,000 pooled, healthy depth." }
    ]
  },
  "ts": "2026-07-30T00:00:00Z"
}

Two failure modes are deliberately thrown before settlement, so a buyer is never charged for a bad or missing answer:

  • 422 invalid_mint when mint is absent or not a resolvable address.
  • 503 data_unavailable when the market reader (DexScreener plus its 15-minute last-known-good copy) has no live market or no 24 hour change for the token.

A failure that happens after settlement (rare for this read-only handler) is answered with paid: true and retry_safe, and the same X-PAYMENT header may re-run the call without a second charge, bounded by X402_PAID_RETRY_MAX and a time window. A call that already completed answers 409 on a replay. The 402 challenge also mirrors its envelope into a base64 PAYMENT-REQUIRED header, capped at 7 KB (the body stays the canonical, complete copy).

This endpoint answers x402 only. It does not opt in to the MPP Payment challenge that some other paid routes offer (see MPP on Solana).

Access control uses the shared bypass hook with the x402:bypass scope (api/_lib/x402/access-control.js), which is how platform-internal callers read the endpoint without paying.


The bazaar schema it publishes

The endpoint declares a v2 bazaar discovery extension (the BAZAAR export in api/x402/token-intel.js), which the shared handler embeds in the 402 challenge and which discovery crawlers index. Its parts:

  • description: the storefront copy, imported from the service catalog so the live challenge can never drift from what the catalog advertises.
  • useCases: token market signal, memecoin due-diligence, agent trading intel.
  • input: { type: 'query', example, schema }. The schema (INPUT_SCHEMA) requires a single mint string, 32 to 64 characters, documented as a Solana base58 mint or an EVM 0x address.
  • output: { type: 'json', example }. The example is a full, realistic response.
  • schema: the meta-schema built by buildBazaarSchema() (api/_lib/x402-spec.js), describing input.{type,method,queryParams} and output.{type,example} in the shape the bazaar validator expects.

OUTPUT_SCHEMA is the response contract, and the resolver hands the same object back as service.output_schema so a client generating code from a resolve never has to fetch the schema separately. It requires mint, signal, headline, rationale, confidence, risk, and ts; signal is constrained to bullish | bearish | neutral; confidence is a number from 0 to 1; risk requires score (integer 0 to 100), level (low | medium | high | critical), summary, and factors.

Alongside the extension, the service-catalog descriptor (api/_lib/service-catalog/services/token-intel.js) is the single written-once listing: api/wk.js derives the /.well-known/x402.json resource entry from it, and the OKX storefront projection reads the same record. Edit the descriptor, not a hand-written mirror. Its serviceName is three.ws Token Oracle and its tags are set through withService() so the entry carries the platform icon and defaults.


The generated snippets

The resolver returns three ready-to-run snippets, all pointed at the resolved endpoint. The page shows them behind a cURL / Node / Agent tab strip with a copy button.

cURL. Step one shows the price by taking the 402; step two replays the same call with the payment header:

# 1) See the price (returns HTTP 402 + payment requirements)
curl -i "https://three.ws/api/x402/token-intel?mint=<MINT_ADDRESS>"

# 2) Pay: sign the requirement from step 1 into a base64 X-PAYMENT header,
#    then replay the same call with it. The Node tab below builds that
#    header for you; export it as X_PAYMENT to finish here in curl.
curl -i -H "X-PAYMENT: $X_PAYMENT" "https://three.ws/api/x402/token-intel?mint=<MINT_ADDRESS>"

There is no x402-fetch CLI to shell out to: the published package is a library (wrapFetchWithPayment, the Node tab), not a bin. Signing is what step two costs you, and the Node and Agent tabs are the two paths that do it for you.

Node, with x402-fetch wrapping a viem wallet client:

import { wrapFetchWithPayment } from 'x402-fetch';
import { createWalletClient, http } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
import { base } from 'viem/chains';

const account = privateKeyToAccount(process.env.PRIVATE_KEY);
const wallet = createWalletClient({ account, chain: base, transport: http() });
const fetchWithPay = wrapFetchWithPayment(fetch, wallet);

const res = await fetchWithPay('https://three.ws/api/x402/token-intel?mint=<MINT_ADDRESS>');
console.log(await res.json());

Agent, from inside a three.ws agent, paying from the agent wallet with no keys in the code:

const intel = await agent.x402.pay('https://three.ws/api/x402/token-intel?mint=<MINT_ADDRESS>');
agent.log(intel.headline, intel.signal, intel.confidence);

The live 402 challenge

The page's "Fetch the live 402 challenge" button calls the generated endpoint with no payment header and prints the response verbatim: the status and the full v2 envelope (x402Version, error, resource, accepts, extensions). That is the same body an x402 client parses, read from the running service rather than a transcript, which makes it the fastest way to confirm the endpoint is payable right now. If the endpoint is unreachable the page says so and offers a retry.


Related

  • x402 on three.ws: the protocol, the wire format, and how the platform settles.
  • x402 paid endpoints: the full catalog of our paid endpoints, their prices, and the X402_PRICE_* override scheme.
  • Receipt Vault: where the buyer's signed receipt for a settled payment to this endpoint can be retrieved.