SDK

Use the Curyo SDK to add hosted reads, frontend attribution, and vote transaction helpers to an existing app.

What It Covers

The core SDK in @curyo/sdk is intentionally framework-agnostic. It gives integrators a clean starting point without forcing a specific wallet library, frontend framework, or backend stack.

• Hosted reads for indexed content, rounds, votes, profiles, categories, stats, and frontend operator records, including each question's selected round settings.
• Vote helpers for stake normalization, frontend-code resolution, tlock commit generation, drand metadata binding, and transfer payload encoding.
• Wallet-agnostic output so the resulting calldata can be passed into wagmi, viem, thirdweb, or a custom signing flow.

Install

The SDK currently lives in the monorepo as packages/sdk and is exposed as @curyo/sdk. Browse the SDK source on GitHub if you want to inspect the current implementation or track new helpers as they land.

import { createCuryoClient } from "@curyo/sdk";
import {
  buildCommitVoteParams,
  buildVoteTransferAndCallData,
  buildVoteTransferPayload,
} from "@curyo/sdk/vote";

Quickstart

Create a client once, then use its hosted read surface wherever your app needs indexed protocol data.

const curyo = createCuryoClient({
  apiBaseUrl: "https://api.curyo.xyz",
  frontendCode: "0x1234567890123456789012345678901234567890",
});

const stats = await curyo.read.getStats();
const { items: contentItems } = await curyo.read.searchContent({
  sortBy: "most_votes",
  limit: 12,
});

const { frontend } = await curyo.read.getFrontend(
  "0x1234567890123456789012345678901234567890",
);

Vote Integration

For vote flows, the SDK helps you prepare the same single-transaction payload the reference app uses. The host app still decides how to sign and submit the transaction. In the redeployed tlock model, commit helpers also thread the reveal target round and drand chain hash through the payload so the contracts can enforce the new metadata bindings on-chain.

const { content } = await curyo.read.getContent("42");
const epochDuration =
  content.openRound?.epochDuration ?? content.roundConfig?.epochDuration ?? 20 * 60;

const commit = await buildCommitVoteParams({
  voter: "0xYourWalletAddress",
  contentId: 42n,
  isUp: true,
  stakeAmount: 2.5,
  epochDuration,
  roundReferenceRatingBps: content.openRound?.referenceRatingBps ?? content.ratingBps ?? 5000,
  defaultFrontendCode: curyo.config.frontendCode,
});

const payload = buildVoteTransferPayload({
  contentId: 42n,
  roundReferenceRatingBps: commit.roundReferenceRatingBps,
  commitHash: commit.commitHash,
  ciphertext: commit.ciphertext,
  frontend: commit.frontend,
  targetRound: commit.targetRound,
  drandChainHash: commit.drandChainHash,
});

const txData = buildVoteTransferAndCallData({
  votingEngineAddress: "0x9999999999999999999999999999999999999999",
  stakeWei: commit.stakeWei,
  payload,
});

Frontend Attribution

If you want votes made through your app to accrue frontend fees, configure a registered frontend operator address and pass it as the default frontend code. That is the bridge between the SDK and the frontend-operator model described in Frontend Integrations.

Agent Examples

Runtime-oriented agent examples live under packages/agents/examples. They cover a copy-paste remote MCP setup, a landing-page pitch review loop, feature acceptance testing for AI-built previews, and notes for chat connectors, Hermes-style persistent agents, Gemini CLI, and backend workers.

• Use landing-pitch-review.ts as the canonical quote -> ask -> wait -> result example.
• Use questions/feature-acceptance-test.json when an agent has a public preview URL and needs humans to follow test steps, vote on whether it works, and leave reproducible failure notes. Results expose afeatureTest summary for bug reports, repro steps, and environment notes.
• Use the bundled JSON snippets when a runtime expects an mcpServers config with transport: "streamable-http".
• Keep live asks stable after submission: start small, top up additively if guidance calls for it, and write the returned publicUrl into the agent's memory or audit log.

What Is Out of Scope

The current SDK is not trying to bundle the full operator stack into one package.

• It does not include wallet UI or React hooks.
• It does not run a keeper or resolution service for you.
• It does not replace an indexer or hosted API deployment.

Those pieces matter for production operators, but they are separate concerns from making integration easy for an existing web app.

If you need the surrounding operator stack, the open-source implementation is split across the keeper and Ponder indexer packages in the monorepo.