@pear-protocol/agent-sdk

TypeScript client for the Pear agent chat API — the conversational assistant (pair-trade ideas, market data, and confirm-before-write trade execution).

• @pear-protocol/agent-sdk — framework-agnostic core (AgentChatClient).
• @pear-protocol/agent-sdk/react — optional React hooks (useAgentChat, useAgentSessions, useLinkStatus, useOnboarding).

Published to public npm (same registry as the org's other @pear-protocol packages — no .npmrc or token needed). The wire types are a single source of truth shared with the backend, so they can't silently drift.

Install

pnpm add @pear-protocol/agent-sdk zod
# only if you use the React hooks:
pnpm add react

zod@^4.1.0 is a required peer dependency (the SDK ships zod schemas at runtime). react@>=18 is required only for the /react hooks.

Quickstart (core)

import { AgentChatClient } from "@pear-protocol/agent-sdk";

const client = new AgentChatClient({
  // Inject your env — the SDK NEVER reads it.
  baseUrl: import.meta.env.VITE_AGENT_PEAR_API_URL,      // Vite
  // baseUrl: process.env.NEXT_PUBLIC_AGENT_PEAR_API_URL, // Next.js
  getToken: () => auth.accessToken,   // returns the freshest JWT; called per request
  tokenVersion: "v2",                 // "v2" wallet JWT (default) | "v3"
});

const { id } = await client.createSession();

for await (const ev of client.streamChat({ sessionId: id, message: "Long ETH short BTC?" })) {
  if (ev.type === "token") process.stdout.write(ev.delta);
  if (ev.type === "done" && ev.result.pendingAction) {
    // A money-moving trade was STAGED, not executed — render Confirm/Cancel.
    await client.confirmTicket(ev.result.pendingAction.ticketId);
    // ...or: await client.cancelTicket(ev.result.pendingAction.ticketId);
  }
}

streamChat yields mode | token | thinking | status | sources events, then a synthetic { type: "done", result }. Token text is delta-only — accumulate ev.delta. The SSE wire has no terminal done frame; the SDK assembles one. If the backend emits a mid-stream error, streamChat throws an AgentChatError. Aborting the stream (the hook's stop(), or your own AbortSignal) also stops generation server-side — the backend detects the disconnect and winds the worker job down at the next safe boundary (never mid-trade-write).

Pass mode to either call to pick the pipeline: "auto" (default) — the agent classifies the turn against its history and runs the right one — "standard" (pin the default pipeline), or "advanced" (force the multi-domain one). The useAgentChat hook's mode also starts at "auto". "auto" is request-only: the stored message carries the RESOLVED "standard"/"advanced", returned as mode on each getMessages row (use it to label which mode answered).

The live stream reports it too: the first event of every turn is { type: "mode", mode: "standard" | "advanced" }. It is the resolved mode, sent for explicit requests as well as auto, never "auto" itself. useAgentChat puts it on the streaming assistant DisplayMessage as mode, so a reply can be labelled while it streams. Older SDK versions ignore the event.

There's also a sync client.sendMessage({ sessionId, message }) returning a ChatResult, and sessions/history methods (listSessions, listSessionSummaries, createSession, getSession, renameSession, deleteSession, getMessages).

Pass images (base64, no data: prefix, capped at 4) to streamChat to attach chart/PnL screenshots — the SSE stream is GET-only and can't carry a body, so streamChat first uploads the images (client.uploadImages → POST /chat/images → bucket keys) and rides those keys on the stream, so an image turn shows live states like a text turn. An image can propose a trade but never auto-executes; the confirm-before-write ticket still guards writes.

On reload, getMessages rows for such a turn carry an attachments array (ChatAttachmentSchema) — { description, imageUrl?, tgFileId?, mime }. imageUrl is a freshly-minted presigned GET; Telegram-originated rows carry tgFileId instead (rendered natively, no presign).

Pass runtimeContext (to either streamChat or sendMessage) to carry request-scoped context from the surface the user is on. Today it holds the in-progress Basket Builder draft under basketContext (RuntimeContextSchema / BasketContextSchema) so the agent reasons over the ACTUAL basket rather than an invented one:

for await (const ev of client.streamChat({
  sessionId: id,
  message: "review my basket and swap the weakest leg",
  surface: "pear_pro",
  runtimeContext: {
    basketContext: {
      name: "AI vs Memes",
      items: [
        { symbol: "NVDA", side: "BUY", weight: 0.5 },
        { symbol: "DOGE", side: "SELL", weight: 0.5 },
      ],
      timeframe: "4Hrs",
      platform: "hyperliquid",
    },
  },
})) { /* … */ }

It is never persisted — injected per-turn for planner routing + basket analysis. On the SSE path it rides the query string (JSON); malformed/oversized payloads are dropped, not rejected. platform accepts "hyperliquid" | "symm" | "lighter" and is failure-tolerant: an unrecognized venue string drops just the field (.catch(undefined)), never the whole draft.

Both streamChat and sendMessage require a surface (pear_v3 | pear_pro | base_mini | web) declaring which Pear client you are — the API rejects requests without a valid one. The agent applies per-surface universe and execution policy — e.g. base_mini surfaces only SYMM assets and is analysis-only. (useAgentChat defaults to pear_v3; set it via the returned setSurface.) The Telegram surfaces are resolved server-side and are not client-declarable.

Voice (speech-to-text)

client.transcribe({ audioBase64, format }) transcribes a voice clip to text via POST /chat/transcribe (multilingual, auto-detect). format is the container — "ogg" | "webm" | "wav" | "mp3" | "m4a" | "flac" (default "webm"). Send the returned text as a normal turn — a voice-originated trade still stages a confirm-before-write ticket.

// Browser: MediaRecorder → base64 → transcribe → review → send
const b64 = await blobToBase64(recordedBlob); // strip the data: prefix
const { text } = await client.transcribe({ audioBase64: b64, format: "webm" });
// put `text` in your input for the user to confirm, then sendMessage(text)

The React hook exposes the same as useAgentChat().transcribe({ audioBase64, format }), returning the transcript string (kept separate from sendMessage so a voice-originated trade isn't auto-submitted). See apps/sdk-example's Composer for a full mic-button implementation.

React

import { useAgentChat } from "@pear-protocol/agent-sdk/react";

function Chat({ client }) {
  const {
    messages, sendMessage, isStreaming, status, stop,
    pendingAction, confirmTicket, cancelTicket, mode, setMode, surface, setSurface,
  } = useAgentChat({ client });

  // render `messages`; if `pendingAction`, show Confirm/Cancel buttons wired to
  // confirmTicket(pendingAction.ticketId) / cancelTicket(pendingAction.ticketId)
}

sendMessage(text, cta?, images?, runtimeContext?) takes an optional third arg — base64 image strings (no data: prefix) — to attach a screenshot: sendMessage("what's this?", undefined, [base64]). Image turns stream just like text (the hook uploads them and streams the reply token-by-token); the sent image also echoes on the user's own bubble. The optional fourth arg carries runtimeContext (e.g. a Basket Builder draft) through to streamChat for that turn.

useAgentChat uses plain React state (no forced data lib). useAgentSessions(client) is a minimal session-list hook; apps using TanStack Query can skip it and call the client directly.

Auth

getToken() returns whatever bearer token the agent API accepts (today a v2 HL-issued JWT). The SDK sends Authorization: Bearer <token> + X-Auth-Token-Version. It does NOT own sign-in — wire it to your wallet/auth flow. A v3 token carries no wallet claim: the API resolves the caller's wallet from their linked Pear user id, so ticket endpoints work once a wallet is linked and answer 401 (AuthError) until then.

Errors

confirmTicket / cancelTicket throw typed errors: TicketExpiredError (410), ForbiddenError (403, not your ticket), ConflictError (409, already handled), AuthError (401). All extend AgentChatError (carries .status).

Trading credential (link status + linking)

The agent executes trades with a V3 engine API key stored against the caller. getLinkStatus() is the one read every surface should gate on — it reports whether a CREDENTIAL is on file, not merely that a link row exists, and it accepts either token scheme:

const status = await client.getLinkStatus();  // backend-verified — don't cache
// { linked, walletAddress?, accountLabel?, tradeAccountId? }

linked: false with a walletAddress is a returning user whose credential predates the V3 engine — they need to link again, not sign up again.

The SDK does not mint keys. Minting is session-only against the Pear gateway, so it belongs to the app that holds the user's session. Mint there, then hand the raw key over — it lives in one local variable for the duration of one POST, and never reaches storage:

// 1. mint on the user's OWN gateway session (same call apps/connect makes)
const res = await fetch(`${GATEWAY}/api-keys`, {
  method: "POST",
  headers: { "Content-Type": "application/json", Authorization: `Bearer ${accessToken}` },
  body: JSON.stringify({ label: "AITA-WEB", scope: "read_write" }),
});
const { key } = await res.json();

// 2. hand it to the agent (v3 session token required; the agent refuses a key
//    whose owner isn't the caller)
await client.linkApiKey({ apiKey: key });

linkApiKey also takes tradeAccountId to pin a default execution target when the key reaches several accounts; omit it and the agent asks at trade time (multipleAccounts: true in the result).

Pass linkCode when the link should bind a Telegram identity — the short-lived code from the ?code= param on the /linkwallet deeplink Telegram sends the user to. Omit it for a web-only link.

React apps use useLinkStatus(client) from ./react — { status, linked, isWorking, error, linkApiKey, refetch } (linked is null while the initial fetch is in flight — render loading, not a gate).

Surfaces that cannot wallet-sign (e.g. a Base mini app) still read the same status: show "trading is off", and send the user to the connect app to link there rather than attempting the mint.

client.linkWallet() / client.unlinkWallet() remain for the v2 wallet-token routes (/auth/link-wallet/self) — those write the link ROW, not the credential, so they answer a different question than useLinkStatus and are not a substitute for it. There is no React hook for them: the one that existed (useWalletLink) reported linked from the link ROW, which contradicts the credential-based meaning useLinkStatus gives that word.

X (Twitter) connection

Linking an X account unlocks the agent's X arc server-side: share-to-X win cards, flex-on-profit pings, a nightly interest digest of the user's own tweets, and tweet-mention trade intake. Requires a linked wallet. The OAuth dance runs in the browser — fetch the authorize URL and redirect:

const status = await client.getXLinkStatus();      // { connected, handle?, stale?, protected? }
const { url } = await client.getXConnectUrl();     // then: window.location.href = url
await client.disconnectX();                        // idempotent

stale: true means X revoked access — offer a re-connect. React apps can use useXLink(client) from ./react — { status, isWorking, error, connect, disconnect, refresh } (status is null while the initial fetch is in flight; connect() resolves { url } for the redirect). See apps/sdk-example's TradeSettings for a working connect/disconnect row.

Onboarding (deterministic, FE-controlled)

A first-time user can be onboarded with a short, deterministic wizard you render yourself — the agent exposes the flow over REST (no in-band chat short-circuit). Every endpoint returns the same state shape so you drive the loop off one type:

let state = await client.getOnboardingState("pear_v3"); // { needsOnboarding, nextQuestion, isLast, answered, total, onboardingState, profile }
while (state.needsOnboarding && state.nextQuestion) {
  const q = state.nextQuestion;
  // closed questions carry q.options: { value, label, description? } — render
  // label + description, submit value. Free-text steps (q.freeform) submit the
  // typed string; skipping one moves on (skipping a closed question bails).
  const value = q.freeform ? userTypedText : userPickedOption.value;
  state = await client.submitOnboardingAnswer("pear_v3", { questionId: q.id, value });
}
// or bail: await client.skipOnboarding("pear_v3");  // smart-skip (parity with TG)
// start over:  await client.resetOnboarding();      // clears picks — NOT for edits
// surface-static question set:  await client.getOnboardingQuestions("pear_v3");

Editing preferences (pre-fill + non-destructive)

getOnboardingState returns profile — the caller's CURRENT picks (experience/tradingStyle/riskAppetite/favoriteSectors/avoidAssets/note, all optional; {} for a new user). favoriteSectors / avoidAssets are set via the favorite_sectors / avoid_assets question ids with a comma-separated string (the server normalizes it to an uppercase token list; "" records none, []). Telegram asks both today; web question sets add them once your UI renders them, but you can submit them at any time. Render an edit form from the full question set

• profile, then submit only the changed field — the server MERGES, so editing one field never wipes the others. Use submitOnboardingAnswer to edit; resetOnboarding is "start over" only.

const [state, questions] = await Promise.all([
  client.getOnboardingState("pear_v3"),
  client.getOnboardingQuestions("pear_v3"),
]);
// Render each question PRE-FILLED: e.g. select state.profile.tradingStyle.
// On a change, submit just that field (non-destructive merge):
await client.submitOnboardingAnswer("pear_v3", { questionId: "risk_appetite", value: "aggressive" });

React apps can use useOnboarding({ client, surface }) from ./react — { needsOnboarding, onboardingState, currentQuestion, questions, profile, isLast, progress, submitAnswer, skip, reset, loading, error, refresh }. Gate your wizard on needsOnboarding once loading is false; for editing, render questions pre-filled from profile and call submitAnswer(questionId, value):

function App({ client }) {
  const ob = useOnboarding({ client, surface: "pear_v3" });
  if (ob.loading) return <Spinner />;
  // First run — sequential wizard off currentQuestion + progress.
  if (ob.needsOnboarding) return <OnboardingWizard {...ob} />;
  // Edit — pre-fill from ob.profile, submit changed fields (no reset):
  // ob.questions.map(q => …current value = ob.profile[…]…
  //   onChange={(value) => ob.submitAnswer(q.id, value)} )
  return <Chat client={client} />;
}

submitAnswer is overloaded: submitAnswer(value) answers the next first-run question; submitAnswer(questionId, value) edits a specific field.

Memory (background recall agent)

The agent auto-distills a short fact-list summary per user from chat history (e.g. "Speaks Dutch", "Avoids >5x leverage"). Read it or wipe it:

const { memory, updatedAt } = await client.getMemory(); // both null until distilled
await client.clearMemory(); // { cleared: true } — also purges the underlying notes

Declared trade mix (onboarding cold-start prior)

The deterministic trade profile (DTP) falls back to this onboarding-declared directional/pair/basket split while observed closed-trade history is thin (<20 trades). Ask-once: asked is true once the caller has answered OR skipped, and stays true — re-submitting still updates the answer, but a polite client shouldn't re-prompt once asked is true.

const { declaredMix, asked } = await client.getDeclaredMix();
// declaredMix is null until answered (never asked, or asked-and-skipped)
await client.setDeclaredMix("pairs"); // "directional" | "pairs" | "baskets" | "mix" | "skip"

React: useDeclaredMix(client) from ./react — mirrors useXLink (status, isWorking, error, setStyle, refresh).

Journal (auto-journaled closed trades)

When a position closes, the background journal agent writes a narrated entry grounded in the computed trade facts (legs, PnL, ratios, …). Read the caller's entries newest-first, cursor-paginated:

const { entries, nextCursor } = await client.getJournal(); // default limit 20, max 50
// entries[].payload carries the raw facts the narrative was grounded in (legs, pnlAmount, pnlPercentage, …)
const nextPage = nextCursor ? await client.getJournal({ cursor: nextCursor }) : null;

Trade tickets (confirm-before-write)

A turn that would move money returns a pendingAction ({ ticketId, action, consequence, connector?, options: ["confirm","cancel"] }) instead of executing. connector (optional) is the execution venue the ticket is bound to — canonical lowercase ("hyperliquid" / "lighter"); the consequence also carries a user-facing "Venue: …" line, so connector is the structured value for a client rendering its own venue affordance. Render it, then call confirmTicket(ticketId) (executes) or cancelTicket(ticketId) (discards). The confirm step is mandatory: nothing a chat turn stages executes until the user confirms it. getTradeSettings() returns { executionEnabled } (the master switch setTradeExecution(enabled) flips).

confirmTicket() resolves a ConfirmResult — { ok, status, result?, positionsSnapshot?, images? }. status is the ticket's settled state (TicketStatusSchema); a confirm most often lands on "EXECUTED" or "FAILED", but can also come back "EXECUTING" when the money path is unresolved (a racing replay, an expired plan token, a binding mismatch) — that is NOT a failure, it means re-read positions before assuming anything. result is the classified venue verdict (ConfirmVerdictResultSchema): for a settled outcome, switch on result.venueStatus (only "filled"/"absent" mean the trade completed; "running"/"unreported"/"partial"/"unfilled" mean submitted-but-unsettled; "failed"/"cancelled" mean refused) or just read the collapsed result.ok. For an unresolved protocol response, result.state is "execution_in_progress" | "missing" | "binding_mismatch" | "timed_out" | "error" — never auto-retry on "missing", "binding_mismatch" or "timed_out" (a timeout means the trade may be live: check positions first). An error result may carry an optional suggestion (what size fits at the requested leverage, or which leverage fits the full size) when the venue refused for margin.