API Reference

Every method returns a Promise.

• R — optional final RequestOptions

• P — { limit?, cursor? }

• IDs accept strings as input and are branded on validated output.

The SDK exposes exact TypeScript contracts through:

Input<'module.method'>;
ParsedInput<'module.method'>;
Output<'module.method'>;

operations exports the corresponding Zod input/output schemas and mutation flags.

TypeScript declarations ship in both .d.ts and .d.cts formats.

Modules and methods

characters

• create(input, R) → Character
• get(id, R) → Character
• update(id, patch, R) → Character
• list({ limit?, cursor?, status?, owner?, world? }, R) → Page<Character>
• archive(id, R) → Character
• hydrate(id, { limit? }, R) → Hydration

events

• capture(input, R) → Event
• captureBatch(inputs, R) → BatchResult<Event>[]
• get(id, R) → Event
• list(characterId, P, R) → Page<Event>

memory

• commit(input, R) → Memory
• recall(query, R) → Page<RecallResult>
• list(characterId, P, R) → Page<Memory>
• forget(id, reason?, R) → Memory
• hydrate(query, R) → Page<RecallResult>
• evolve({ memoryId, content?, salience?, tags?, provenance? }, R) → Memory

relationships

• get(characterId, subjectId, R) → Relationship
• update(input, R) → Relationship
• list(characterId, P, R) → Page<Relationship>

inventory

• grant(input, R) → InventoryItem
• transfer({ characterId, toCharacterId, itemId, quantity }, R) → { from: InventoryItem | null, to: InventoryItem }
• remove({ characterId, itemId, quantity }, R) → InventoryItem | null
• verify({ characterId, itemId, quantity? }, R) → Verification
• list(characterId, P, R) → Page<InventoryItem>

achievements

• unlock({ characterId, key, name, description?, metadata? }, R) → Achievement
• get(id, R) → Achievement
• list(characterId, P, R) → Page<Achievement>

identity

• resolve({ characterId }, R) → Identity
• create({ characterId, wallet, publicKey?, portability? }, R) → Identity
• checkpoint({ characterId }, R) → Checkpoint
• publish({ checkpointId }, R) → Checkpoint
• verify({ checkpointId }, R) → Verification
• getHistory(characterId, P, R) → Page<Checkpoint>

sessions

• start({ characterId, worldId?, playerId?, hydrate?, metadata? }, R) → Session
• end(id, { summarize?, checkpoint? }, R) → Session
• get(id, R) → Session

client

• sync({ id }, { checkpoint?, ...R }) → Hydration
• health(R) → { status: "ok", network, timestamp }
• withContext(overrides) → FourBTDClient

Characters

Character creation requires name and owner.

Optional fields include:

description
traits
goals
world
metadata

metadata must contain valid JSON values.

Character updates accept a partial creation input.

Archived characters remain readable but reject new character-state mutations. archive is idempotent.

Character versions track profile updates and archival. Memory, relationship, inventory, session, and identity versions track changes to their respective entities.

Use state roots to detect aggregate character-state changes.

Public Exports

The SDK exports branded IDs for:

Character
Event
Memory
Session
Player
World
Item
Achievement
Checkpoint

It also exports entity, pagination, error, and configuration types, along with all runtime schemas.

Core interfaces include:

Transport;
Storage;
StoreState;
IdentityAdapter;
CheckpointSigner;
Clock;
IdGenerator;
Logger;

Concrete adapters and transports are also exported.

Utilities include:

canonical;
stateRoot;
redact;
systemClock;
randomId;
noopLogger;
checkpointMemo;
isSolanaPublicKey;
validateUrl;

Errors

Typed SDK errors include:

FourBTDError;
AuthenticationError;
AuthorizationError;
ValidationError;
NotFoundError;
ConflictError;
RateLimitError;
TimeoutError;
NetworkError;
ServerError;
AbortError;

All SDK errors expose:

code
message
status?
requestId?
details?
retryAfterMs?
retryable

toJSON() returns safe error data.

Error utilities are also exported:

isFourBTDError;
isRetryableError;
errorForStatus;