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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
fix(v1): tell callers what to do next when a mint, name, or upstream lookup fails
nirholas878e48db2f94
diff --git a/api/tx/solana/[action].js b/api/tx/solana/[action].jsindex d34f6b838..7b1736c44 100644--- a/api/tx/solana/[action].js+++ b/api/tx/solana/[action].js@@ -84,6 +84,19 @@ async function resolveMint(connection, mintPk) {return { programId, decimals: info.decimals };}+// Derive an associated token account, answering 400 rather than 500 when the+// owner is off the ed25519 curve. A program-derived address (an AMM vault, an+// escrow) has no standard ATA and no keypair to sign with, so a caller who pastes+// one has made an input mistake: name the side that is wrong instead of letting+// TokenOwnerOffCurveError surface as an opaque internal error.+function associatedTokenAddress(mint, owner, programId, side) {+ try {+ return getAssociatedTokenAddressSync(mint, owner, false, programId, ASSOCIATED_TOKEN_PROGRAM_ID);+ } catch {+ throw clientError('invalid_owner', `${side} is a program-derived address and has no associated token account`);+ }+}+// ── build-transfer ────────────────────────────────────────────────────────────const transferSchema = z.object({@@ -139,8 +152,8 @@ async function handleBuildTransfer(req, res) {return error(res, 400, 'invalid_amount', `amount rounds to zero at ${decimals} decimals`);}- const senderATA = getAssociatedTokenAddressSync(mint, senderPubkey, false, programId, ASSOCIATED_TOKEN_PROGRAM_ID);- const recipientATA = getAssociatedTokenAddressSync(mint, recipientPubkey, false, programId, ASSOCIATED_TOKEN_PROGRAM_ID);+ const senderATA = associatedTokenAddress(mint, senderPubkey, programId, 'sender');+ const recipientATA = associatedTokenAddress(mint, recipientPubkey, programId, 'recipient');// Tell the sender their balance is short BEFORE they approve a transaction// that can only fail on-chain and still cost them the fee.diff --git a/api/v1/index.js b/api/v1/index.jsindex 00ac48aa7..385f737be 100644--- a/api/v1/index.js+++ b/api/v1/index.js@@ -1,7 +1,7 @@-// GET /api/v1 — discovery document for the unified three.ws API.+// GET /api/v1: discovery document for the unified three.ws API.//// The single front door: one machine-readable index of every versioned-// endpoint, its auth requirement, scope, and parameters — so an agent or+// endpoint, its auth requirement, scope, and parameters, so an agent or// developer can discover the whole surface from one call. Rendered from the// shared catalog (api/v1/_catalog.js) so it can never drift from the live routes.@@ -16,7 +16,7 @@ export default defineEndpoint({handler: () => ({...API_META,endpoints: CATALOG,- // Aggregated third-party APIs — many endpoints behind one key/bill, each+ // Aggregated third-party APIs: many endpoints behind one key/bill, each// callable via BYOK, a three.ws plan, or x402 pay-per-call. See /api/v1/x.aggregator: {base_url: '/api/v1/x',diff --git a/api/v1/market/intel.js b/api/v1/market/intel.jsindex 471470e45..85605bfde 100644--- a/api/v1/market/intel.js+++ b/api/v1/market/intel.js@@ -1,8 +1,8 @@-// GET /api/v1/market/intel — recent narrative / market intelligence items.+// GET /api/v1/market/intel: recent narrative / market intelligence items.//// Unified-API surface over the aixbt bridge (api/_lib/aixbt.js). The shared// upstream key is metered per-deployment, so on top of the gateway's-// per-principal budget this also consumes the global aixbt ceiling — one caller+// per-principal budget this also consumes the global aixbt ceiling: one caller// (or many) can't drain the shared key.import { defineEndpoint, fail } from '../../_lib/gateway.js';@@ -17,13 +17,13 @@ export default defineEndpoint({handler: async ({ query }) => {// Throw the platform's canonical missing-env error (matches wrap()'s// `missingEnv` regex in api/_lib/http.js) so the client actually gets- // "this endpoint is not configured on this deployment" — a hand-rolled+ // "this endpoint is not configured on this deployment", a hand-rolled// fail(503, 'not_configured', <message>) instead falls into wrap's// generic sanitized-5xx branch and the message never reaches the caller.if (!aixbtEnabled()) throw new Error('Missing required env var: AIXBT_API_KEY');const g = await limits.aixbtGlobal();- if (!g.success) fail(429, 'rate_limited', 'market intelligence is busy — retry shortly');+ if (!g.success) fail(429, 'rate_limited', 'market intelligence is busy, retry shortly');let result;try {diff --git a/api/v1/pump/curve.js b/api/v1/pump/curve.jsindex 352e387ef..79ab819c9 100644--- a/api/v1/pump/curve.js+++ b/api/v1/pump/curve.js@@ -1,10 +1,10 @@// GET /api/v1/pump/curve?mint=<mint>//-// Free, keyless bonding-curve / graduation status for a pump.fun token —+// Free, keyless bonding-curve / graduation status for a pump.fun token:// registers the free Crypto Data API's bonding-curve reader// (api/_lib/pump-bonding.js `getBondingStatus`, already live at// GET /api/crypto/bonding) under the versioned, cataloged /api/v1 surface so-// agents can discover it via GET /api/v1. Same engine, same response shape —+// agents can discover it via GET /api/v1. Same engine, same response shape:// a thin wrapper, not a fork.//// Answers: % to graduation, SOL in the curve, tokens remaining, market cap, and@@ -38,11 +38,11 @@ export default defineEndpoint({fail(400,'not_pumpfun_mint',- `${mint} is not a pump.fun bonding-curve token — it never launched on pump.fun or isn't indexed. Discover live pump.fun mints at /api/v1/pump/launches or /api/v1/pump/trending.`,+ `${mint} is not a pump.fun bonding-curve token: it never launched on pump.fun or isn't indexed. Discover live pump.fun mints at /api/v1/pump/launches or /api/v1/pump/trending.`,);}if (result.kind === 'upstream_down') {- fail(503, 'upstream_unavailable', 'pump.fun data source is temporarily unreachable — retry shortly');+ fail(503, 'upstream_unavailable', 'pump.fun data source is temporarily unreachable, retry shortly');}const s = result.status;diff --git a/api/v1/pump/launches.js b/api/v1/pump/launches.jsindex c1fd97b68..d232e38f6 100644--- a/api/v1/pump/launches.js+++ b/api/v1/pump/launches.js@@ -1,14 +1,14 @@// GET /api/v1/pump/launches?limit=24&offset=0&network=mainnet&agent_id=<uuid>&min_tier=<tier>//// Free, public, paginated feed of every coin launched THROUGH three.ws (a-// pump_agent_mints row), joined with the launching agent — the platform's own+// pump_agent_mints row), joined with the launching agent: the platform's own// launch directory, distinct from a generic pump.fun-wide new-mint feed. Powers// the /launches page and the agent-detail "launched coins" card; registered// here under the versioned, cataloged /api/v1 surface so agents can discover// three.ws's own launch history via GET /api/v1.//// The query lives in api/_lib/pump-agent-launches.js `queryAgentLaunches`,-// shared with GET /api/pump/launches (api/pump/[action].js) — one query, two+// shared with GET /api/pump/launches (api/pump/[action].js): one query, two// doors, so the page and this endpoint can never drift.import { defineEndpoint, fail } from '../../_lib/gateway.js';@@ -24,7 +24,7 @@ export default defineEndpoint({method: 'GET',auth: 'public',handler: async ({ req, res, query }) => {- // Dedicated-shared budget with the sibling free pump.fun v1 reads — this+ // Dedicated-shared budget with the sibling free pump.fun v1 reads: this// hits the database on a cache miss, so it caps a scripted enumeration flood.const rl = await limits.publicIp(clientIp(req));if (!rl.success) return rateLimited(res, rl, 'pump launches is capped at 60 requests/min per IP');diff --git a/api/v1/pump/search.js b/api/v1/pump/search.jsindex 7020f69e0..d726c3546 100644--- a/api/v1/pump/search.js+++ b/api/v1/pump/search.js@@ -1,16 +1,16 @@// GET /api/v1/pump/search?q=<query>&limit=8//// Free, keyless text search over Solana pump.fun / meme tokens by name,-// symbol, or mint — the one pump.fun capability with no live equivalent+// symbol, or mint: the one pump.fun capability with no live equivalent// elsewhere in the platform's free crypto surfaces (trending, bonding-curve// progress, launches, and whale activity all already ship as free endpoints-// under /api/crypto/* — see docs/crypto-api.md). This registers the same+// under /api/crypto/*, see docs/crypto-api.md). This registers the same// Birdeye-first/pump.fun-fallback search the site's command palette already// uses (api/pump/search.js) under the versioned, cataloged /api/v1 surface so// agents can discover it via GET /api/v1.//-// Both routes share one implementation — api/_lib/pump-search.js-// `searchPumpTokens` — so this is a thin wrapper, not a fork.+// Both routes share one implementation, api/_lib/pump-search.js+// `searchPumpTokens`, so this is a thin wrapper, not a fork.import { defineEndpoint, fail } from '../../_lib/gateway.js';import { limits, clientIp } from '../../_lib/rate-limit.js';@@ -22,20 +22,20 @@ export default defineEndpoint({method: 'GET',auth: 'public',handler: async ({ req, res, query }) => {- // Dedicated per-IP budget on top of the gateway's shared apiV1 burst guard —+ // Dedicated per-IP budget on top of the gateway's shared apiV1 burst guard:// this fans out to a real Birdeye/pump.fun upstream on every cache miss, so// it caps a scripted enumeration flood the same way the sibling free reads do.const rl = await limits.publicIp(clientIp(req));if (!rl.success) return rateLimited(res, rl, 'pump search is capped at 60 requests/min per IP');const q = typeof query.q === 'string' ? query.q.trim().slice(0, 64) : '';- if (!q) fail(400, 'validation_error', 'query param "q" is required — pass a token name, symbol, or mint');+ if (!q) fail(400, 'validation_error', 'query param "q" is required: pass a token name, symbol, or mint');const rawLimit = Number(query.limit || '8');const limit = Math.min(20, Math.max(1, Number.isFinite(rawLimit) ? Math.floor(rawLimit) : 8));const results = await searchPumpTokens(q, limit);- // A miss is a valid, common outcome — [] with 200, never a 404/500.+ // A miss is a valid, common outcome: [] with 200, never a 404/500.res.setHeader('cache-control', 'public, max-age=15, s-maxage=30');return { results, count: results.length, q };},diff --git a/api/v1/pump/trending.js b/api/v1/pump/trending.jsindex d74c403d8..1670b6b53 100644--- a/api/v1/pump/trending.js+++ b/api/v1/pump/trending.js@@ -1,14 +1,14 @@// GET /api/v1/pump/trending?window=5m|1h|24h&limit=1..25&source=pumpfun|all//-// Free, keyless momentum-ranked "what's hot right now" feed for Solana tokens —+// Free, keyless momentum-ranked "what's hot right now" feed for Solana tokens:// registers the free Crypto Data API's trending engine (api/_lib/crypto-trending.js// `composeTrending`, already live at GET /api/crypto/trending) under the// versioned, cataloged /api/v1 surface so agents can discover it via GET /api/v1.// Same engine, same ranking signal (documented in crypto-trending.js +-// docs/crypto-api.md) — this is a thin wrapper, not a fork, capped slimmer (25+// docs/crypto-api.md): this is a thin wrapper, not a fork, capped slimmer (25// vs 50) to keep the v1 door fast.//-// Tokens are ranked by a 0–100 momentum score fusing windowed volume, buy+// Tokens are ranked by a 0-100 momentum score fusing windowed volume, buy// pressure, a volume-spike signal, and price change across pump.fun,// DexScreener, and (best-effort) GMGN smart money. Never 500s: every source// failing yields 200 with an empty ranking + a note.@@ -27,7 +27,7 @@ export default defineEndpoint({auth: 'public',handler: async ({ req, res, query }) => {// Dedicated-shared budget with the sibling free pump.fun v1 reads and the- // /api/crypto/trending door this wraps — fans out to real upstreams on a+ // /api/crypto/trending door this wraps, fans out to real upstreams on a// cache miss, so this caps a scripted enumeration flood.const rl = await limits.publicIp(clientIp(req));if (!rl.success) return rateLimited(res, rl, 'pump trending is capped at 60 requests/min per IP');@@ -42,7 +42,7 @@ export default defineEndpoint({// A live, momentum-ranked feed shifts minute to minute but doesn't need// sub-minute freshness; a short CDN cache absorbs bursts of agents polling// the same window. An empty result (all sources down) is cached only- // briefly so we retry the live feeds soon — set before returning so the+ // briefly so we retry the live feeds soon, set before returning so the// gateway's secure-by-default no-store doesn't override it.res.setHeader('cache-control',diff --git a/api/v1/pump/whales.js b/api/v1/pump/whales.jsindex f9e4b3e9a..e97d21a59 100644--- a/api/v1/pump/whales.js+++ b/api/v1/pump/whales.js@@ -1,9 +1,9 @@// GET /api/v1/pump/whales?limit=1..25[&mint=<mint>][&minSol=<n>]//-// Free, keyless whale / large-buy detection across pump.fun — the read+// Free, keyless whale / large-buy detection across pump.fun: the read// version of the whale-activity oracle that otherwise sits behind the paid// GET /api/x402/pump-agent-audit ("mode":"whale_activity"). Reports FACTS only-// (which wallets moved how much SOL, and when) — no invented "bullish/bearish+// (which wallets moved how much SOL, and when), no invented "bullish/bearish// signal + confidence": that decorative framing is dropped here on purpose so// the agent draws its own conclusion from the same underlying trades the paid// oracle scores.@@ -11,7 +11,7 @@// The scan lives in api/_lib/pump-whale-scan.js (`scanTokenWhales` /// `scanMarketWhales`), the SAME shared module behind the free// GET /api/crypto/whales endpoint and (via the same pump.fun trade shape) the-// paid oracle — one whale-detection implementation, three doors, never a+// paid oracle: one whale-detection implementation, three doors, never a// fourth copy-paste.//// (omit mint) → top whale WALLETS active across pump.fun's top coins right now@@ -32,7 +32,7 @@ export default defineEndpoint({auth: 'public',handler: async ({ req, res, query }) => {// Dedicated-shared budget with the sibling free pump.fun v1 reads and the- // /api/crypto/whales door this shares a scan engine with — a market-scope+ // /api/crypto/whales door this shares a scan engine with: a market-scope// scan fans out to several coins' trade feeds, so this bounds that cost.const rl = await limits.publicIp(clientIp(req));if (!rl.success) return rateLimited(res, rl, 'pump whales is capped at 60 requests/min per IP');@@ -68,7 +68,7 @@ export default defineEndpoint({const body = {scope: result.scope,mint: result.mint,- // Facts only — the decorative bullish/bearish "signal" the paid oracle+ // Facts only: the decorative bullish/bearish "signal" the paid oracle// and /api/crypto/whales report is deliberately dropped here.wallets: result.whales,whale_count: result.whaleCount,@@ -78,7 +78,7 @@ export default defineEndpoint({source: result.source,};if (result.degraded) {- body.note = 'pump.fun feed is temporarily unavailable — returning an empty whale set; retry shortly';+ body.note = 'pump.fun feed is temporarily unavailable, returning an empty whale set; retry shortly';}// The feed was rate-limited and these rows came from the last-known-good// pull. Real trades, a few minutes old: say so rather than imply live.diff --git a/api/v1/resolve.js b/api/v1/resolve.jsindex 8cf99a41f..19b63268b 100644--- a/api/v1/resolve.js+++ b/api/v1/resolve.js@@ -1,4 +1,4 @@-// GET /api/v1/resolve — free, keyless name resolution across ENS + SNS.+// GET /api/v1/resolve: free, keyless name resolution across ENS + SNS.//// Wraps the platform's existing resolvers instead of reimplementing them:// - .eth (ENS) → `ensResolveAddress` / `ensLookupName` from@@ -6,13 +6,13 @@// (one eth_call per direction). That module's header records why the// previous ethers `resolveName` walk made this endpoint 503 in production.// - .sol (SNS) → `resolveSnsName` / `reverseLookupAddress` from-// src/solana/sns.js — the exact module api/sns.js and api/sns-subdomain.js+// src/solana/sns.js, the exact module api/sns.js and api/sns-subdomain.js// already share. No Bonfida call is reimplemented here.//// Forward: ?name=<x>.eth | ?name=<x>.sol → { name, chain, address, source }// Reverse: ?address=<addr>[&chain=ethereum|solana] → { address, chain, name, source }-// Reverse only runs the direction the underlying resolver already supports —-// ethers' lookupAddress for ENS, SNS's getFavoriteDomain for SNS — both of+// Reverse only runs the direction the underlying resolver already supports:+// ethers' lookupAddress for ENS, SNS's getFavoriteDomain for SNS, both of// which the wrapped modules above already implement, so no half-built// placeholder direction is exposed.//@@ -47,8 +47,8 @@ async function resolveForward(rawName, res) {503,'ens_unavailable',err?.message === 'ens_timeout'- ? 'ENS resolution timed out — retry shortly'- : 'ENS resolution failed — retry shortly',+ ? 'ENS resolution timed out, retry shortly'+ : 'ENS resolution failed, retry shortly',);}if (!address) fail(404, 'not_found', `${name} did not resolve to an Ethereum address`);@@ -66,7 +66,7 @@ async function resolveForward(rawName, res) {fail(400,'unsupported_suffix',- 'name must end in .eth (ENS) or .sol (SNS) — no other suffix is supported',+ 'name must end in .eth (ENS) or .sol (SNS): no other suffix is supported',);}@@ -96,8 +96,8 @@ async function resolveReverse(rawAddress, chainHint, res) {503,'ens_unavailable',err?.message === 'ens_reverse_timeout'- ? 'ENS reverse resolution timed out — retry shortly'- : 'ENS reverse resolution failed — retry shortly',+ ? 'ENS reverse resolution timed out, retry shortly'+ : 'ENS reverse resolution failed, retry shortly',);}if (!name) fail(404, 'not_found', `${rawAddress} has no primary ENS name`);diff --git a/api/v1/robinhood/chain.js b/api/v1/robinhood/chain.jsindex e0d8c564e..dd1464dff 100644--- a/api/v1/robinhood/chain.js+++ b/api/v1/robinhood/chain.js@@ -1,4 +1,4 @@-// GET /api/v1/robinhood/chain — Robinhood Chain (4663) stats.+// GET /api/v1/robinhood/chain: Robinhood Chain (4663) stats.//// Free, keyless. Real data: block height + gas (Blockscout), TVL now + 90-day// history (DefiLlama /chain/robinhood-chain). Cached upstream (15s stats, 120s