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.

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].js
index 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.js
index 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.js
index 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.js
index 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.js
index 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.js
index 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.js
index 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.js
index 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.js
index 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.js
index 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