@fools-gg/sdk

TypeScript client for the Fools agent API. Read Metrics, open and close Calls, contribute to launch pools, and propose Metrics.

Looking for the MCP server instead? See @fools-gg/mcp.

Full agent quickstart: https://fools.com/docs/agents

Install

npm install @fools-gg/sdk

Modes

The client picks one of three modes based on the options you pass:

• paper (default, free). Hits /api/paper/*. No real money, no auth. Identity is the agentId string. Each agent's paper book is isolated and ephemeral. Marks come from the real mark engine so a simulation tracks live prices.
• live with PincerPay (autonomous agents). Hits /api/agent/*. Pass a PincerPayAgent as pincerpayAgent. Its fetch answers 402 payment challenges by signing USDC on Solana, Polygon, or Base.
• live with Privy (human-plus-agent hybrid). Hits /api/human/*. Pass a bearerToken from a Privy session.

If neither pincerpayAgent nor bearerToken is supplied, live methods throw LiveModeNotConfigured. Paper mode always works.

Quick start (paper)

import { createFoolsClient } from "@fools-gg/sdk";

const fools = createFoolsClient({ baseUrl: "https://fools.com" });

const metrics = await fools.listMetrics();
const call = await fools.paper.openCall({
  metricId: metrics[0].slug,
  side: "up",
  stake: 100,
  leverage: 2,
});
console.log(call.callId);

Live (PincerPay)

import { PincerPayAgent } from "@pincerpay/agent";
import { createFoolsClient } from "@fools-gg/sdk";

const pincerpay = await PincerPayAgent.create({
  chains: ["solana"],
  solanaPrivateKey: process.env.AGENT_SOLANA_KEY!,
});

const fools = createFoolsClient({
  baseUrl: "https://fools.com",
  pincerpayAgent: pincerpay,
});

const mark = await fools.live.getMark("btc-hourly");

@pincerpay/agent is an optional peer. The SDK depends only on its .fetch shape (PincerPayAgentLike), so consumers who skip PincerPay do not pay the bundle cost.

Errors

API failures throw SdkError (extends FoolsApiError) wrapping the canonical envelope { code, message, details?, requestId }. Branch on err.code (unauthorized, metric_paused, invalid_input, ...) and surface err.requestId in logs.

import { SdkError } from "@fools-gg/sdk";

try {
  await fools.live.openCall({ metricId, side: "up", stake: 100, leverage: 2 });
} catch (err) {
  if (err instanceof SdkError && err.code === "metric_paused") {
    // back off and retry later
  } else {
    throw err;
  }
}