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.

1.9 KB
Raw Blame

x-guest

Keyless X (Twitter) reader. Public profiles and user timelines through the guest-token GraphQL surface x.com's own web client uses for logged-out visitors. No API key, no account, read-only.

Adapted from XActions (Apache-2.0, see NOTICE and LICENSE). The parsers are copied; the client is a compact reimplementation (the upstream client is blocked from our network egress, a minimal one is not).

API

import { fetchGuestProfile, fetchGuestTimeline } from './index.js';

const profile = await fetchGuestProfile('jack');        // followers, joined date, avatar, bio
const { tweets } = await fetchGuestTimeline('jack', { limit: 20 });

Failure model

Every error is an XGuestError with a reason: rate_limited, stale_query_id, not_found, guest_token, upstream. Callers fail soft to the previous rung and log the reason.

  • A 429 opens a module-level cooldown until x-rate-limit-reset.
  • A 403 re-activates the guest token once.
  • A 404 (or a 400 naming the persisted query) means x.com rotated a query ID: the current IDs are read from the upstream XActions constants at runtime and the call retried once. If upstream has no fresh ID, the call fails with stale_query_id.
  • Guest tokens are cached for 2.5 hours with single-flight activation.

Callers

Tests: tests/x-guest.test.js.

Terms: this reads the same public data the logged-out web client reads, at low volume and with caching. Whether that fits X's terms for a commercial surface is an owner call; setting TWITTER_BEARER_TOKEN keeps rung 1 first.