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
// Shared client for the Solana Developer Platform (SDP) — the Solana
// Foundation's enterprise API for custodial wallets, SPL token issuance,
// payments, and compliance screening (https://platform.solana.com).
//
// Keeps SDP_API_KEY server-side and returns parsed JSON. Throws an Error
// tagged with { status, code, detail } so proxy/handlers map upstream
// failures to the right HTTP code without leaking the key. Never fabricates
// data — upstream errors surface verbatim.
//
// Auth: project-scoped API key in the Authorization header (Bearer). The
// `/health` and `/openapi.json` surfaces need no key, so health checks work
// even on a deployment that hasn't been wired with credentials yet.
// Production API host. Override with SDP_API_BASE to point at the sandbox or a
// self-hosted deployment (the SDP API is a Cloudflare Worker — see
// solana-foundation/solana-developer-platform). Sandbox vs. production is
// otherwise selected by which API key you use; the wire surface is identical.
const DEFAULT_BASE = 'https://api.solana.com';
// Versioned API segments the proxy is willing to forward (everything under
// `/v1`). The list mirrors the SDP Hono router's v1 mounts so we never forward
// to a path the upstream doesn't serve — and so this can't be turned into an
// open proxy to arbitrary hosts/paths. Keep in sync with the upstream
// `apps/sdp-api/src/app.ts` router.
export const SDP_V1_RESOURCES = Object.freeze([
'organizations',
'api-keys',
'counterparties',
'members',
'auth',
'projects',
'rpc',
'issuance',
'wallets',
'onboarding',
'payments',
'compliance',
]);
// Top-level (un-versioned) paths the upstream serves directly. `health` and
// `openapi.json` are unauthenticated; `llms.txt` is the machine-readable doc.
export const SDP_TOP_LEVEL = Object.freeze(['health', 'openapi.json', 'llms.txt']);
export function sdpConfigured() {
return !!process.env.SDP_API_KEY;
}
export function sdpBase() {
const raw = process.env.SDP_API_BASE || DEFAULT_BASE;
return raw.replace(/\/+$/, '');
}
// True when `path` (no leading slash, no query) is a surface the upstream
// actually serves. Used by the proxy allowlist.
export function isSdpAllowedPath(path) {
const clean = String(path || '').replace(/^\/+/, '');
if (!clean || clean.includes('..')) return false;
// The path is concatenated into the upstream URL, and the URL parser there
// collapses "%2e%2e" / ".%2E" / tab-split dots into real traversal segments
// and treats "?", "#" and "\\" as structure. The route surface is plain
// lowercase path segments, so refuse everything else before it gets that far.
if (!/^[A-Za-z0-9_\-.]+(\/[A-Za-z0-9_\-.]+)*\/?$/.test(clean)) return false;
if (clean.split('/').some((seg) => seg === '.')) return false;
if (SDP_TOP_LEVEL.includes(clean)) return true;
if (clean === 'health/ready') return true;
if (clean.startsWith('v1/')) {
const resource = clean.slice(3).split('/')[0];
return SDP_V1_RESOURCES.includes(resource);
}
return false;
}
// Whether a given SDP path requires our server-side API key. Health and the
// public doc/spec surfaces don't, so they stay reachable on an unconfigured
// deployment (returning the upstream's real status rather than a fake 503).
export function sdpPathNeedsKey(path) {
const clean = String(path || '').replace(/^\/+/, '');
if (clean === 'health' || clean === 'health/ready') return false;
if (clean === 'openapi.json' || clean === 'llms.txt') return false;
return true;
}
// Core request. Returns { status, headers, body } where body is parsed JSON
// when the upstream sends JSON, otherwise the raw text. Throws (tagged with
// { status }) only on transport failure or missing-credential — HTTP error
// statuses from the upstream are returned, not thrown, so the proxy can relay
// the upstream's own error envelope and status code faithfully.
export async function sdpRequest(
path,
{ method = 'GET', query, body, headers = {}, timeoutMs = 15_000 } = {},
) {
const clean = String(path || '').replace(/^\/+/, '');
if (!isSdpAllowedPath(clean)) {
throw Object.assign(new Error(`SDP path not allowed: ${clean}`), { status: 404 });
}
const needsKey = sdpPathNeedsKey(clean);
const apiKey = process.env.SDP_API_KEY;
if (needsKey && !apiKey) {
throw Object.assign(
new Error('Solana Developer Platform is not configured (set SDP_API_KEY)'),
{ status: 503 },
);
}
let url = `${sdpBase()}/${clean}`;
if (query && typeof query === 'object') {
const qs = new URLSearchParams();
for (const [k, v] of Object.entries(query)) {
if (v != null && v !== '') qs.set(k, String(v));
}
const s = qs.toString();
if (s) url += `?${s}`;
}
const reqHeaders = { accept: 'application/json', ...headers };
// Only the privileged routes carry our key. The public doc/health surfaces
// are reachable unauthenticated, so attributing those fetches to our org key
// would let an anonymous caller burn our upstream quota for nothing.
if (needsKey && apiKey) reqHeaders.authorization = `Bearer ${apiKey}`;
const init = { method, headers: reqHeaders, signal: AbortSignal.timeout(timeoutMs) };
if (body != null && method !== 'GET' && method !== 'HEAD') {
init.body = typeof body === 'string' ? body : JSON.stringify(body);
reqHeaders['content-type'] = 'application/json';
}
let upstream;
try {
upstream = await fetch(url, init);
} catch (e) {
const reason = e?.name === 'TimeoutError' ? 'timed out' : e?.message || 'unreachable';
throw Object.assign(new Error(`Solana Developer Platform ${reason}`), { status: 504 });
}
const ct = upstream.headers.get('content-type') || '';
const raw = await upstream.text();
let parsed = raw;
if (ct.includes('application/json') && raw) {
try {
parsed = JSON.parse(raw);
} catch {
parsed = raw;
}
}
return {
status: upstream.status,
contentType: ct,
traceId: upstream.headers.get('x-sdp-trace-id') || null,
body: parsed,
};
}
// Convenience wrapper that throws on any non-2xx, surfacing the upstream's
// structured error ({ error: { code, message } }). Use from server-side code
// that wants a value-or-throw contract rather than the raw envelope.
export async function sdpCall(path, opts = {}) {
const res = await sdpRequest(path, opts);
if (res.status >= 200 && res.status < 300) return res.body;
const err = res.body?.error;
const message = err?.message || (typeof res.body === 'string' ? res.body : 'request failed');
throw Object.assign(new Error(`SDP ${res.status}: ${String(message).slice(0, 300)}`), {
status: res.status,
code: err?.code || 'sdp_error',
traceId: res.traceId,
});
}
// ── Typed helpers for the common surfaces ────────────────────────────────────
export function sdpHealth() {
return sdpCall('health');
}
export function sdpListWallets(query) {
return sdpCall('v1/wallets', { query });
}
export function sdpGetWallet(walletId) {
return sdpCall(`v1/wallets/${encodeURIComponent(walletId)}`);
}
export function sdpCreateWallet(payload, idempotencyKey) {
return sdpCall('v1/wallets', {
method: 'POST',
body: payload,
headers: idempotencyKey ? { 'idempotency-key': idempotencyKey } : {},
});
}
export function sdpListTokens(query) {
return sdpCall('v1/issuance/tokens', { query });
}
export function sdpCreateToken(payload, idempotencyKey) {
return sdpCall('v1/issuance/tokens', {
method: 'POST',
body: payload,
headers: idempotencyKey ? { 'idempotency-key': idempotencyKey } : {},
});
}
export function sdpListTransfers(query) {
return sdpCall('v1/payments/transfers', { query });
}
export function sdpCreateTransfer(payload, idempotencyKey) {
return sdpCall('v1/payments/transfers', {
method: 'POST',
body: payload,
headers: idempotencyKey ? { 'idempotency-key': idempotencyKey } : {},
});
}
// Screen a Solana address against the SDP compliance providers.
// payload: { address, network?, intent? }.
export function sdpScreenAddress(payload) {
return sdpCall('v1/compliance/address-screenings', { method: 'POST', body: payload });
}