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
// Browser-safe Solana JSON-RPC proxy.
//
// Public RPC (api.mainnet-beta.solana.com) returns 403 to many browser
// requests, breaking /studio's launch panel (balance polling, tx send,
// confirmation). This proxy forwards JSON-RPC POSTs to Helius when
// HELIUS_API_KEY is set, otherwise to the public RPC server-side (which
// the Solana Labs nodes don't block from datacentre IPs the same way).
//
// Usage from browser:
// new Connection('/api/solana-rpc') -> mainnet
// new Connection('/api/solana-rpc?net=devnet') -> devnet
//
// Hardening: this proxy fronts a keyed (paid) upstream, so it is rate-limited
// per-IP with a global hourly ceiling and only forwards an allowlist of the
// read/send methods the launch panel needs — never the expensive scan methods
// (getProgramAccounts, getBlock*) that would let an anonymous caller drain the
// upstream quota.
import { cors, method, wrap, readJson, error, rateLimited, reportServerError } from './_lib/http.js';
import { limits, clientIp } from './_lib/rate-limit.js';
import {
solanaRpcEndpoints,
makeRotatingFetch,
classifyRpcBody,
} from './_lib/solana/connection.js';
// Methods a browser Connection needs to read balances/accounts, build, simulate,
// send, and confirm transactions. Deliberately excludes getProgramAccounts and
// the getBlock* family — heavy scans that have no place in the launch panel and
// are the prime vector for upstream quota abuse.
const ALLOWED_METHODS = new Set([
'getBalance',
'getAccountInfo',
'getMultipleAccounts',
'getLatestBlockhash',
'getRecentBlockhash',
'isBlockhashValid',
'getFeeForMessage',
'getMinimumBalanceForRentExemption',
'getSignatureStatuses',
'getSignaturesForAddress',
'getTransaction',
'sendTransaction',
'simulateTransaction',
'getTokenAccountBalance',
'getTokenAccountsByOwner',
'getTokenSupply',
// Inherently bounded — returns at most the top 20 holders of one mint.
'getTokenLargestAccounts',
'getEpochInfo',
'getSlot',
'getBlockHeight',
'getGenesisHash',
'getHealth',
'getVersion',
]);
// getProgramAccounts is an unbounded scan in the general case — the prime
// vector for draining the keyed upstream — so it is NOT in ALLOWED_METHODS.
// We permit it ONLY when the caller supplies a `filters` array containing at
// least one memcmp (a dataSize filter alone still scans the whole program)
// that bounds the result set (e.g. a memcmp on a specific mint, as the pump dashboard's bonding
// curve probe does). A filtered, slice-limited query is cheap; a bare scan is
// still refused.
function isBoundedProgramScan(entry) {
if (entry.method !== 'getProgramAccounts') return false;
const opts = Array.isArray(entry.params) ? entry.params[1] : null;
return !!(
opts &&
Array.isArray(opts.filters) &&
opts.filters.some((f) => f && typeof f === 'object' && f.memcmp && typeof f.memcmp === 'object')
);
}
// Cap batch requests so a single POST can't fan out into hundreds of upstream
// calls and sidestep the per-request rate limit.
const MAX_BATCH = 10;
// Returns a fetch function that rotates across Helius → Alchemy → Ankr → public,
// skipping any endpoint currently in the process-wide cooldown map (same cooldown
// state shared by solanaConnection() so a quota-dead provider stays skipped).
function upstreamFetch(network) {
const endpoints = solanaRpcEndpoints(network === 'devnet' ? 'devnet' : 'mainnet');
return makeRotatingFetch(endpoints);
}
// Validate one or a batch of JSON-RPC payloads. Returns an error code string,
// or null when every entry is a well-formed call to an allowlisted method.
export function rejectReason(body) {
const entries = Array.isArray(body) ? body : [body];
if (entries.length === 0) return 'empty_request';
if (entries.length > MAX_BATCH) return 'batch_too_large';
for (const e of entries) {
if (!e || typeof e !== 'object') return 'malformed_request';
if (typeof e.method !== 'string') return 'malformed_request';
if (ALLOWED_METHODS.has(e.method)) continue;
if (isBoundedProgramScan(e)) continue; // filtered getProgramAccounts is allowed
if (e.method === 'getProgramAccounts') return 'unbounded_scan';
return 'method_not_allowed';
}
return null;
}
export default wrap(async function handler(req, res) {
// Open to any origin: this is a public, unauthenticated, method-allowlisted
// proxy whose whole job is to be callable from a browser, and the abuse
// surface is unchanged by CORS (curl never needed it). Opening it lets
// statically-hosted three.ws surfaces reach mainnet, notably the standalone
// agent deployer at nirholas.github.io/metaplex-agent-mcp, which otherwise
// has no mainnet path at all because api.mainnet-beta.solana.com 403s
// browser origins. The per-IP and global rate limits below still apply.
if (cors(req, res, { methods: 'POST,OPTIONS', origins: '*', credentials: false })) return;
if (!method(req, res, ['POST'])) return;
const ip = clientIp(req);
const [ipRl, globalRl] = await Promise.all([limits.solanaRpcIp(ip), limits.solanaRpcGlobal()]);
if (!ipRl.success || !globalRl.success) {
return rateLimited(res, ipRl, 'too many RPC requests');
}
const url = new URL(req.url, 'http://x');
const network = url.searchParams.get('net') === 'devnet' ? 'devnet' : 'mainnet';
let body;
try {
body = await readJson(req, 200_000);
} catch (e) {
return error(res, e.status || 400, 'bad_body', 'failed to read JSON body');
}
const reason = rejectReason(body);
if (reason) {
const msg =
reason === 'method_not_allowed'
? 'this RPC method is not permitted through the proxy'
: reason === 'unbounded_scan'
? 'getProgramAccounts requires a bounding `filters` array through this proxy'
: reason === 'batch_too_large'
? `batch exceeds ${MAX_BATCH} requests`
: 'malformed JSON-RPC request';
const status = reason === 'method_not_allowed' || reason === 'unbounded_scan' ? 403 : 400;
return error(res, status, reason, msg);
}
let upstream;
try {
const rotateFetch = upstreamFetch(network);
upstream = await rotateFetch(null, {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify(body),
});
} catch (e) {
return error(res, 502, 'upstream_error', 'rpc upstream failed');
}
const text = await upstream.text();
// Defense-in-depth: the rotating fetch already validates every body it returns,
// but never let a malformed payload reach a browser web3.js Connection — it would
// throw an opaque StructError (or silently mis-read an empty `[]`) instead of a
// clean error the caller can handle. If the upstream body isn't a well-formed
// JSON-RPC response, surface an honest 502 keyed to the same JSON-RPC id.
const classified = classifyRpcBody(text);
if (classified) {
const id = Array.isArray(body) ? null : body?.id ?? null;
// A provider returning a body web3.js can't parse is a real upstream
// degradation worth seeing. Capture genuine 5xx through the boundary
// (deduped on the classification reason, so a flapping provider alerts once
// an hour, not per request) and thread the ref into the JSON-RPC error
// `data` so a caller can quote it without breaking the strict envelope.
// Capacity classifications (429) are expected provider backpressure, not a
// server fault — don't alert on those.
let ref;
if ((classified.status ?? 502) >= 500) {
ref = reportServerError(new Error(`rpc upstream returned an unusable response: ${classified.reason}`), {
code: 'rpc_upstream_unusable',
status: 502,
});
}
res.statusCode = 502;
res.setHeader('content-type', 'application/json; charset=utf-8');
res.setHeader('cache-control', 'no-store');
res.end(JSON.stringify({ jsonrpc: '2.0', id, error: { code: -32603, message: 'rpc upstream returned an unusable response', ...(ref ? { data: { ref } } : {}) } }));
return;
}
res.statusCode = upstream.status;
res.setHeader('content-type', 'application/json; charset=utf-8');
res.setHeader('cache-control', 'no-store');
// The rotation answers an idempotent read from its last-good body when every
// lane is down (api/_lib/solana/connection.js); pass the age through so a
// browser can render "as of N minutes ago" instead of trusting it as live.
const staleMs = upstream.headers.get('x-solana-rpc-stale');
if (staleMs) {
res.setHeader('x-solana-rpc-stale', staleMs);
res.setHeader('access-control-expose-headers', 'x-solana-rpc-stale');
}
res.end(text);
});