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
// @three-ws/irl — geofenced, real-world presence for agents and avatars.
// Thin client over the public /api/irl/* endpoints (the SDK twin of the live
// /irl surface): proof-of-presence minting, GPS pin placement, the geofenced
// nearby feed, and the real-world interaction log. See README.md for the full
// reference. Presence is the gate on every read — you can only query a point you
// are actually standing at.
import { createHttp, ThreeWsError } from './http.js';
import { prune, normToken, normalizeEnum, presenceFix, fixHeader } from './shared.js';
import { createDropsApi } from './drops.js';
import { createWorldLinesApi } from './world-lines.js';
export { ThreeWsError, PaymentRequiredError, DEFAULT_BASE_URL } from './http.js';
// Token lifetime the mint endpoint advertises (api/_lib/irl-presence.js
// FIX_TTL_SEC). Re-checkIn() once it lapses — the nearby read rejects an expired
// fix with `fix_required`.
const FIX_TTL_SEC = 180;
// Precision of the geohash cell carried on the presence token and used as the
// re-mint trigger as a viewer walks (FIX_CELL_PRECISION, ~153 m cell).
const FIX_CELL_PRECISION = 7;
const INTERACTION_TYPES = ['view', 'tap', 'message', 'pay'];
const PLACEMENT_KINDS = ['precise', 'approximate'];
/**
* Create an IRL client bound to a base URL, fetch, and optional auth/device token.
* For most callers the default exports (`checkIn()`, `nearby()`, …) backed by a
* shared client are enough; use this when you want to reuse configuration — a
* payment-aware fetch for an agent's `x402_endpoint`, a custom origin, or a
* default anonymous device token — across many calls.
*
* @param {object} [options]
* @param {string} [options.baseUrl] API origin (default https://three.ws).
* @param {typeof fetch} [options.fetch] fetch implementation (default global fetch).
* @param {string} [options.apiKey] bearer session token for signed-in ownership.
* @param {string} [options.deviceToken] anonymous device credential (header-only).
* @param {Record<string,string>} [options.headers] default headers on every call.
*/
export function createIrl(options = {}) {
const request = createHttp(options);
const defaultDeviceToken = normToken(options.deviceToken);
// Resolve the device token for a call: per-call override → client default. Sent
// in the `x-irl-device` header (never the URL — it is a bearer credential).
function deviceToken(opts) {
return normToken(opts && opts.deviceToken) || defaultDeviceToken;
}
function deviceHeader(opts, extra) {
const h = { ...(extra || {}) };
const tok = deviceToken(opts);
if (tok) h['x-irl-device'] = tok;
return h;
}
/**
* Establish presence at a location and mint a short-lived proof-of-presence
* token. With no argument it reads the browser Geolocation API; pass
* `{ lat, lng, accuracy? }` to supply a fix yourself (Node, or any non-browser
* source). Wraps `POST /api/irl/fix-token` and returns the token alongside the
* fix so `nearby()` can prove the read.
*/
async function checkIn(input, opts = {}) {
const fix = await resolveFix(input);
const minted = await request('/api/irl/fix-token', {
method: 'POST',
body: { lat: fix.lat, lng: fix.lng, accuracy: fix.accuracy },
signal: opts.signal,
});
if (!minted || typeof minted.token !== 'string') {
throw new ThreeWsError('fix-token did not return a presence token.', { code: 'bad_response', body: minted });
}
return {
lat: fix.lat,
lng: fix.lng,
accuracy: fix.accuracy ?? null,
token: minted.token,
expiresIn: minted.expires_in ?? FIX_TTL_SEC,
// The precision-7 geohash the fix fell in — the client's "re-mint on cell
// change" trigger. Server-supplied; fall back to a local encode so a
// dev/preview response without it still carries the cell.
cell: minted.cell || encodeGeohash(fix.lat, fix.lng, FIX_CELL_PRECISION),
raw: minted,
};
}
/**
* Read agents within the radius of where you checked in. Wraps
* `GET /api/irl/pins?lat=&lng=&radius=` with the presence token in the
* `x-irl-fix` header. Only answers for the coarse area the token was minted in.
*/
async function nearby(presence, opts = {}) {
const { lat, lng, token } = presenceFix(presence, 'nearby()');
// The fix token rides a header, gating the read to a genuine presence.
const headers = fixHeader(token, opts.headers);
const radius = opts.radius;
if (radius !== undefined && !Number.isFinite(radius)) {
throw new ThreeWsError('nearby() radius must be a finite number of metres.', { code: 'invalid_input' });
}
const res = await request('/api/irl/pins', {
query: { lat, lng, radius },
headers: deviceHeader(opts, headers),
signal: opts.signal,
});
return (res?.pins || []).map(shapePin);
}
/**
* Drop a 3D agent at a coordinate. Wraps `POST /api/irl/pins`. Returns the
* created pin and a `permanent` flag (true for signed-in owners, false — 7-day
* expiry — for anonymous device placements).
*/
async function placePin(input, opts = {}) {
const p = input || {};
const lat = Number(p.lat);
const lng = Number(p.lng);
if (!Number.isFinite(lat) || !Number.isFinite(lng)) {
throw new ThreeWsError('placePin() needs finite `lat` and `lng`.', { code: 'invalid_input' });
}
if (lat < -90 || lat > 90 || lng < -180 || lng > 180) {
throw new ThreeWsError('placePin() coordinates are out of range.', { code: 'invalid_input' });
}
const placementKind = normalizeEnum(p.placementKind, PLACEMENT_KINDS, 'placementKind');
const body = prune({
lat,
lng,
heading: p.heading,
avatarUrl: p.avatarUrl,
avatarName: p.avatarName,
caption: p.caption,
agentId: p.agentId,
x402Endpoint: p.x402Endpoint,
anchor: p.anchor,
room: p.room,
vps: p.vps,
placementKind,
fuzzRadiusM: p.fuzzRadiusM,
});
const res = await request('/api/irl/pins', {
method: 'POST',
body,
headers: deviceHeader(opts),
signal: opts.signal,
});
return { pin: shapeOwnPin(res?.pin), raw: res };
}
/**
* List the pins you placed. With a device token, wraps `GET /api/irl/pins/mine`
* (the token rides the `x-irl-device` header); for a signed-in session,
* `GET /api/irl/pins?mine=1`.
*/
async function myPins(opts = {}) {
const tok = deviceToken(opts);
const res = tok
? await request('/api/irl/pins/mine', { headers: deviceHeader(opts), signal: opts.signal })
: await request('/api/irl/pins', { query: { mine: '1' }, signal: opts.signal });
return (res?.pins || []).map(shapeOwnPin);
}
/**
* Log a real-world encounter. Wraps `POST /api/irl/interactions`. `agent_id`
* and owner are taken from the pin, never the caller.
*/
async function interact(input, opts = {}) {
const i = input || {};
const pinId = i.pinId ?? i.pin_id;
if (!pinId || typeof pinId !== 'string') {
throw new ThreeWsError('interact() needs a `pinId`.', { code: 'invalid_input' });
}
const type = i.type === undefined ? undefined : normalizeEnum(i.type, INTERACTION_TYPES, 'type');
const body = prune({
pinId,
type,
message: i.message,
replyTo: i.replyTo,
payload: i.payload,
// `pay` settlement fields — passed through to the on-chain dedupe + earnings.
signature: i.signature,
currencyMint: i.currencyMint,
amount: i.amount,
network: i.network,
device_type: i.deviceType,
});
const res = await request('/api/irl/interactions', {
method: 'POST',
body,
headers: deviceHeader(opts),
signal: opts.signal,
});
return shapeInteraction(res);
}
/** Remove one pin you placed. Wraps `DELETE /api/irl/pins?id=`. */
async function removePin(id, opts = {}) {
if (!id || typeof id !== 'string') {
throw new ThreeWsError('removePin() needs a pin id.', { code: 'invalid_input' });
}
const res = await request('/api/irl/pins', {
method: 'DELETE',
query: { id },
headers: deviceHeader(opts),
signal: opts.signal,
});
return { ok: Boolean(res?.ok), raw: res };
}
/**
* Wipe every pin placed from a device token in one round-trip. Wraps
* `DELETE /api/irl/pins?all=1` — requires a device token (the bulk purge is
* scoped strictly to the credential that placed the pins).
*/
async function purgePins(opts = {}) {
if (!deviceToken(opts)) {
throw new ThreeWsError('purgePins() needs a device token (set one via createIrl/configure or pass { deviceToken }).', { code: 'invalid_input' });
}
const res = await request('/api/irl/pins', {
method: 'DELETE',
query: { all: '1' },
headers: deviceHeader(opts),
signal: opts.signal,
});
return { ok: Boolean(res?.ok), deleted: Number(res?.deleted) || 0, raw: res };
}
// Money Drops & World Lines — the same request core, device token, and
// presence contract, wrapped for /api/irl/drops and /api/irl/world-lines.
const drops = createDropsApi({ request, deviceHeader });
const worldLines = createWorldLinesApi({ request, deviceHeader });
return { checkIn, nearby, placePin, myPins, interact, removePin, purgePins, ...drops, ...worldLines };
}
// ── Default zero-config client (the `import { checkIn }` path) ───────────────
// A module-level client built lazily so the common case needs no setup, plus a
// `configure()` to set a base URL / default device token once for the module.
let shared = null;
let sharedOptions = {};
function defaultClient() {
return (shared ||= createIrl(sharedOptions));
}
/**
* Set module-level defaults for the zero-config functions: base origin (defaults
* to https://three.ws) and an anonymous device token sent header-only on every
* write. Rebuilds the shared client.
*/
export function configure(opts = {}) {
sharedOptions = { ...sharedOptions, ...opts };
shared = null;
return sharedOptions;
}
/** Establish presence and mint a proof-of-presence token. */
export function checkIn(input, opts) {
return defaultClient().checkIn(input, opts);
}
/** Read agents within the radius of where you checked in. */
export function nearby(presence, opts) {
return defaultClient().nearby(presence, opts);
}
/** Drop a 3D agent at a coordinate. */
export function placePin(input, opts) {
return defaultClient().placePin(input, opts);
}
/** List the pins you placed. */
export function myPins(opts) {
return defaultClient().myPins(opts);
}
/** Log a real-world encounter with an agent. */
export function interact(input, opts) {
return defaultClient().interact(input, opts);
}
/** Remove one pin you placed. */
export function removePin(id, opts) {
return defaultClient().removePin(id, opts);
}
/** Wipe every pin placed from a device token. */
export function purgePins(opts) {
return defaultClient().purgePins(opts);
}
// ── Money Drops (real value escrowed at real-world spots) ────────────────────
/** Live drops within the radius of where you checked in (presence-gated). */
export function nearbyDrops(presence, opts) {
return defaultClient().nearbyDrops(presence, opts);
}
/** One drop by id — coarse (~110 m) location for anyone but the owner. */
export function getDrop(id, opts) {
return defaultClient().getDrop(id, opts);
}
/** Your created drops (every status) plus your claim receipts. */
export function myDrops(opts) {
return defaultClient().myDrops(opts);
}
/** Place value in the real world — returns the escrow address to fund. */
export function createDrop(input, opts) {
return defaultClient().createDrop(input, opts);
}
/** Confirm your signed funding transfer on-chain and activate the drop. */
export function fundDrop(input, opts) {
return defaultClient().fundDrop(input, opts);
}
/** Claim a drop you are standing at — a real on-chain release to your wallet. */
export function claimDrop(input, opts) {
return defaultClient().claimDrop(input, opts);
}
/** Cancel an unclaimed drop you created — a real on-chain refund sweep. */
export function cancelDrop(id, opts) {
return defaultClient().cancelDrop(id, opts);
}
// ── World Lines (agent-signed proof-of-presence AR quests) ──────────────────
/** Quests near where you checked in (fix-gated; distance coarsened to 10 m). */
export function nearbyWorldLines(presence, opts) {
return defaultClient().nearbyWorldLines(presence, opts);
}
/** Public, coordinate-free discovery — region roll-up or one region's quests. */
export function browseWorldLines(opts) {
return defaultClient().browseWorldLines(opts);
}
/** One quest for the AR detail view — full challenge only when co-located. */
export function getWorldLine(id, opts) {
return defaultClient().getWorldLine(id, opts);
}
/** Place a quest anchored to a pin you own, signed by an agent you own. */
export function createWorldLine(input, opts) {
return defaultClient().createWorldLine(input, opts);
}
/** Your placed quests + a coarse completion heatmap (signed-in). */
export function myWorldLines(opts) {
return defaultClient().myWorldLines(opts);
}
/** The proof-of-presence collectibles you've earned. */
export function myCollectibles(opts) {
return defaultClient().myCollectibles(opts);
}
/** Start a completion at the spot — issues the single-use nonce. */
export function challengeWorldLine(input, opts) {
return defaultClient().challengeWorldLine(input, opts);
}
/** Finish the interaction and receive the agent-signed proof collectible. */
export function completeWorldLine(input, opts) {
return defaultClient().completeWorldLine(input, opts);
}
/** Independently re-verify a proof's agent signature (public). */
export function verifyProof(proofId, opts) {
return defaultClient().verifyProof(proofId, opts);
}
// ── Fix resolution ──────────────────────────────────────────────────────────
// Resolve a fix to { lat, lng, accuracy? } from an explicit object, a presence
// already carrying a fix, or — with no input — the browser Geolocation API.
async function resolveFix(input) {
if (input && Number.isFinite(Number(input.lat)) && Number.isFinite(Number(input.lng))) {
return {
lat: Number(input.lat),
lng: Number(input.lng),
accuracy: Number.isFinite(Number(input.accuracy)) ? Number(input.accuracy) : undefined,
};
}
if (input !== undefined && input !== null) {
throw new ThreeWsError('checkIn() needs `{ lat, lng }` — or call it with no argument in a browser to read GPS.', { code: 'invalid_input' });
}
return readBrowserFix();
}
// Read a single GPS fix from the browser Geolocation API. Rejects with a typed
// error outside a browser so a Node caller gets a clear "pass { lat, lng }".
function readBrowserFix() {
const geo = typeof navigator !== 'undefined' ? navigator.geolocation : undefined;
if (!geo || typeof geo.getCurrentPosition !== 'function') {
throw new ThreeWsError('No Geolocation API available — pass an explicit `{ lat, lng }` to checkIn().', { code: 'no_geolocation' });
}
return new Promise((resolve, reject) => {
geo.getCurrentPosition(
(pos) => resolve({ lat: pos.coords.latitude, lng: pos.coords.longitude, accuracy: pos.coords.accuracy }),
(err) => reject(new ThreeWsError(`Geolocation failed: ${err?.message || 'permission denied'}`, { code: 'geolocation_failed' })),
{ enableHighAccuracy: true, timeout: 15000, maximumAge: 0 },
);
});
}
// ── Response shaping (snake_case → camelCase, with a .raw escape hatch) ──────
// A pin from the public nearby feed — the allow-list projection (never user_id
// or device_token). Coordinates are server-coarsened to ~1.1 m.
function shapePin(r) {
if (!r || typeof r !== 'object') return r;
return {
id: r.id,
agentId: r.agent_id ?? null,
lat: r.lat,
lng: r.lng,
heading: r.heading ?? 0,
distanceM: r.distance_m ?? null,
avatarUrl: r.avatar_url ?? null,
avatarName: r.avatar_name ?? null,
caption: r.caption ?? null,
x402Endpoint: r.x402_endpoint ?? null,
viewCount: Number(r.view_count) || 0,
avatarVersion: Number(r.avatar_version) || 0,
placedAt: r.placed_at ?? null,
anchorHeightM: r.anchor_height_m ?? null,
anchorYawDeg: r.anchor_yaw_deg ?? null,
anchorQuat: r.anchor_quat ?? null,
anchorSource: r.anchor_source ?? null,
gpsAccuracyM: r.gps_accuracy_m ?? null,
altitudeM: r.altitude_m ?? null,
roomId: r.room_id ?? null,
relEastM: r.rel_east_m ?? null,
relNorthM: r.rel_north_m ?? null,
originLat: r.origin_lat ?? null,
originLng: r.origin_lng ?? null,
originYawDeg: r.origin_yaw_deg ?? null,
isMine: Boolean(r.is_mine),
raw: r,
};
}
// A pin the caller owns (from placePin / myPins) — carries owner-only fields the
// public feed strips, plus the `permanent` flag from the create response.
function shapeOwnPin(r) {
if (!r || typeof r !== 'object') return r;
return {
id: r.id,
agentId: r.agent_id ?? null,
lat: r.lat,
lng: r.lng,
heading: r.heading ?? 0,
avatarUrl: r.avatar_url ?? null,
avatarName: r.avatar_name ?? null,
caption: r.caption ?? null,
x402Endpoint: r.x402_endpoint ?? null,
viewCount: Number(r.view_count) || 0,
avatarVersion: Number(r.avatar_version) || 0,
placedAt: r.placed_at ?? null,
expiresAt: r.expires_at ?? null,
permanent: 'permanent' in r ? Boolean(r.permanent) : (r.expires_at == null),
raw: r,
};
}
// A logged interaction from POST /api/irl/interactions.
function shapeInteraction(res) {
if (!res || typeof res !== 'object') return res;
const ix = res.interaction || {};
return {
ok: Boolean(res.ok),
id: ix.id ?? res.id ?? null,
type: ix.type ?? null,
createdAt: ix.created_at ?? null,
deduped: Boolean(res.deduped),
self: Boolean(res.self),
notified: Boolean(res.notified),
raw: res,
};
}
// Geohash encoder — identical lattice to api/_lib/geohash.js so a fix maps to the
// same precision-7 cell the server keys on. Used as the local fallback for a
// presence cell and to compare cells across a walk-up poll.
const GEOHASH_BASE32 = '0123456789bcdefghjkmnpqrstuvwxyz';
export function encodeGeohash(lat, lng, precision = FIX_CELL_PRECISION) {
if (!Number.isFinite(lat) || !Number.isFinite(lng)) return '';
let idx = 0;
let bit = 0;
let evenBit = true;
let geohash = '';
let latMin = -90, latMax = 90;
let lngMin = -180, lngMax = 180;
while (geohash.length < precision) {
if (evenBit) {
const mid = (lngMin + lngMax) / 2;
if (lng >= mid) { idx = idx * 2 + 1; lngMin = mid; } else { idx = idx * 2; lngMax = mid; }
} else {
const mid = (latMin + latMax) / 2;
if (lat >= mid) { idx = idx * 2 + 1; latMin = mid; } else { idx = idx * 2; latMax = mid; }
}
evenBit = !evenBit;
if (++bit === 5) {
geohash += GEOHASH_BASE32[idx];
bit = 0;
idx = 0;
}
}
return geohash;
}