Skip to main content
@ixo/oracles-client-sdk is the frontend agent-client interface used by applications that connect users to deployed oracles.
@ixo/oracle-agent-sdk (Agentic Oracles ADK) is for scaffolding, implementing, and deploying oracle services into the network.

​
Choose the right SDK

NeedUse
Build a user-facing React app that talks to existing oracles@ixo/oracles-client-sdk
Scaffold, implement, and deploy an oracle service@ixo/oracle-agent-sdk (Agentic Oracles ADK)
For service-side development, see Agentic Oracles ADK.

​
What this SDK provides

Use this SDK to:
  • authenticate with Matrix-backed user context
  • create and manage oracle chat sessions
  • stream responses in real time
  • render tool outputs and custom UI components
  • expose browser tools and AG-UI actions
  • handle payment-required claim flows
  • start optional live audio/video calls

​
Install

pnpm add @ixo/oracles-client-sdk zod
Or: 
npm install @ixo/oracles-client-sdk zod
The SDK targets React 18+.

​
Prerequisites

Before integrating, prepare:
  • a React app
  • a wallet object with IXO address, DID, and Matrix access token
  • a transaction signing function (transactSignX or equivalent)
  • the target oracle DID
  • oracle endpoint resolution from entity services, or explicit URL overrides
type Wallet = {
  address: string;
  did: string;
  matrix: {
    accessToken: string;
  };
};

type TransactSignX = (
  messages: unknown[],
  memo?: string
) => Promise<unknown | undefined>;

​
Quick start

import { useEffect, useState } from "react";
import {
  OraclesProvider,
  renderMessageContent,
  useChat,
  useOracleSessions,
} from "@ixo/oracles-client-sdk";

const wallet = {
  address: "ixo1...",
  did: "did:ixo:entity:user...",
  matrix: { accessToken: "syt_..." },
};

async function transactSignX(
  messages: unknown[],
  memo?: string
): Promise<unknown | undefined> {
  return Promise.resolve(undefined);
}

export default function App() {
  return (
    <OraclesProvider initialWallet={wallet} transactSignX={transactSignX}>
      <OracleChat oracleDid="did:ixo:entity:oracle..." />
    </OraclesProvider>
  );
}

function OracleChat({ oracleDid }: { oracleDid: string }) {
  const [activeSessionId, setActiveSessionId] = useState<string>();
  const { sessions, createSession, isLoading } = useOracleSessions(oracleDid);

  useEffect(() => {
    if (activeSessionId || isLoading) return;
    const existing = sessions?.[0]?.sessionId;
    if (existing) {
      setActiveSessionId(existing);
      return;
    }
    createSession().then((s) => setActiveSessionId(s.sessionId));
  }, [activeSessionId, isLoading, sessions, createSession]);

  if (!activeSessionId) return <div>Preparing oracle session...</div>;
  return <ChatWindow oracleDid={oracleDid} sessionId={activeSessionId} />;
}

function ChatWindow({
  oracleDid,
  sessionId,
}: {
  oracleDid: string;
  sessionId: string;
}) {
  const { messages, sendMessage, isSending, isLoading, error } = useChat({
    oracleDid,
    sessionId,
    streamingMode: "batched",
    onPaymentRequiredError: (claimIds) => {
      console.log("Payment required for claims:", claimIds);
    },
  });

  if (isLoading) return <div>Loading conversation...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <section>
      {messages.map((message) => (
        <article key={message.id}>{renderMessageContent(message.content)}</article>
      ))}
      <form
        onSubmit={(event) => {
          event.preventDefault();
          const formData = new FormData(event.currentTarget);
          const message = String(formData.get("message") ?? "").trim();
          if (!message) return;
          sendMessage(message);
          event.currentTarget.reset();
        }}
      >
        <input name="message" placeholder="Ask the oracle..." disabled={isSending} />
        <button type="submit" disabled={isSending}>
          {isSending ? "Sending..." : "Send"}
        </button>
      </form>
    </section>
  );
}

​
Payments, memory, and errors

Use useContractOracle for contract/invite/pay actions, useMemoryEngine for room memory operations, and RequestError for claim-aware error handling. 
import {
  RequestError,
  useChat,
  useContractOracle,
  useMemoryEngine,
} from "@ixo/oracles-client-sdk";

function OracleOperations({ oracleDid }: { oracleDid: string }) {
  const [claimIds, setClaimIds] = useState<string[]>([]);

  const chat = useChat({
    oracleDid,
    sessionId: "session-id",
    onPaymentRequiredError: (requiredClaimIds) => setClaimIds(requiredClaimIds),
  });

  const contract = useContractOracle({
    params: {
      oracleDid,
      userClaimCollectionId: "claim-collection-id",
      adminAddress: "ixo1admin...",
      claimId: "claim-id",
      agentQuota: 1,
    },
  });

  const memory = useMemoryEngine(oracleDid);

  async function send(message: string) {
    try {
      await chat.sendMessage(message);
    } catch (error) {
      if (RequestError.isRequestError(error) && error.claims) {
        console.log("Outstanding claims:", error.claims);
        return;
      }
      throw error;
    }
  }

  return (
    <div>
      <p>Outstanding claim IDs: {claimIds.join(", ") || "none"}</p>
      <button onClick={() => contract.inviteOracle()} disabled={contract.isInvitingOracle}>
        Invite oracle
      </button>
      <button onClick={() => contract.contractOracle({ useAuthz: true })} disabled={contract.isContractingOracle}>
        Contract oracle
      </button>
      <button onClick={() => contract.payClaim()} disabled={contract.isPayingClaim}>
        Pay claim
      </button>
      <button onClick={() => memory.enableMemoryEngine("@memory-engine:matrix.example")}>
        Enable memory
      </button>
      <button onClick={() => send("Review this claim")}>Send message</button>
    </div>
  );
}
Keep transaction signing explicit and role-gate room administration, memory actions, and payment controls.

​
API summary

APIUse it for
OraclesProviderProvide wallet and transaction context.
useOracleSessionsCreate, list, delete, and refetch sessions.
useChatSend messages, stream responses, and handle payment-required events.
renderMessageContentRender message metadata into UI.
useAgActionRegister validated frontend actions callable by the oracle.
useContractOracleContract oracles, invite to rooms, and settle claims.
useMemoryEngineManage room membership and memory-engine setup.
useGetOpenIdTokenRetrieve Matrix OpenID tokens.
getOpenIdTokenManually fetch an OpenID token.
useLiveAgentStart/end optional live calls.

Agentic Oracles ADK

Service-side SDK for building and deploying oracle services.

Agentic Oracles

Conceptual architecture and operating model.

SignX SDK

Integrate user-authorized signing into oracle workflows.

IXO Matrix

Learn how rooms and shared context support conversations.