Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.altheia.xyz/llms.txt

Use this file to discover all available pages before exploring further.

import { Altheia } from "@altheia-xyz/sdk";

const altheia = new Altheia(config);

​
new Altheia(config)

​
Config

FieldTypeDefaultNotes
agentPdastring—Required. The agent’s AgentAccount PDA from the dashboard.
agentIdstring—Legacy DB UUID. Use agentPda for new code.
apiKeystring—Required in production. Backend returns 401 without it.
endpointstringhttps://api.altheia.xyzOverride only for self-hosted.
failureMode"open" | "closed""open"What to do when the backend is unreachable.
timeoutMsnumber1500Per-request timeout for check and report.
cacheTTLnumber0Cache repeat-action decisions in seconds. 0 disables.
You must pass at least one of agentPda or agentId. If both are set, agentPda wins.

​
Failure mode

  • "open" (default): on backend timeout or error, return allowed: true with reason: "sdk_unreachable_failopen". Swig’s on-chain scope is the floor that catches over-cap actions. Use this when uptime matters more than strict enforcement.
  • "closed": throw AltheiaConnectionError. Use this for agents that move money — halt is safer than swing.

​
Example

const altheia = new Altheia({
  agentPda: process.env.ALTHEIA_AGENT_PDA!,
  apiKey: process.env.ALTHEIA_API_KEY!,
  failureMode: "closed",
  timeoutMs: 5000,
});

​
Methods

MethodWhat it does
guard(action, fn)Check policy, run if allowed, audit the result.
check(action)Check policy without running anything.
report(event)Attach an outcome to an audit row.
ping(status)Send a heartbeat. Best-effort.
policy()Fetch the current policy in scope for this agent.