Starter examples

npx tsx check-before-acting.ts chainlink

// Check a token with CoinGraph before your agent acts on it. Needs Node 18 or later, and no packages.
//
//   npx tsx check-before-acting.ts chainlink            free check, no key needed
//   npx tsx check-before-acting.ts solana 5000          sized to your order, needs COINGRAPH_KEY, costs 5 credits
//
// Exit code: 0 proceed, 1 caution or avoid, 2 the check could not be completed.
// CoinGraph never executes, custodies or advises. Your agent decides what to do with the answer.

const API = process.env.COINGRAPH_API ?? "https://coingraph.ai/api/v1";
const KEY = process.env.COINGRAPH_KEY;

type Reason = { dimension: string; text: string; source: string };
type Check = {
  id: string;
  as_of: string;
  data: {
    token: { id: string; symbol: string };
    verdict: "proceed" | "caution" | "avoid";
    confidence: number;
    reasons: Reason[];
    size_check: { order_usd: number; estimated_impact_pct: number | string } | null;
  };
};

async function checkToken(token: string, sizeUsd?: number): Promise<{ check: Check; charged: string | null; left: string | null }> {
  if (sizeUsd !== undefined && !KEY) throw new Error("A sized check needs a key. Create one at https://coingraph.ai/account/keys, then set COINGRAPH_KEY.");
  const res = await fetch(sizeUsd === undefined ? `${API}/evaluate/${encodeURIComponent(token)}` : `${API}/evaluate`, {
    method: sizeUsd === undefined ? "GET" : "POST",
    headers: { "content-type": "application/json", ...(KEY ? { authorization: `Bearer ${KEY}` } : {}) },
    body: sizeUsd === undefined ? undefined : JSON.stringify({ token, size_usd: sizeUsd }),
    signal: AbortSignal.timeout(30_000),
  });
  const body = await res.json();
  if (!res.ok) throw new Error(`${res.status} ${body.error?.code ?? "error"}: ${body.error?.message ?? "request failed"}`);
  return { check: body, charged: res.headers.get("x-credits-charged"), left: res.headers.get("x-credits-remaining") };
}

async function main() {
  const [token = "chainlink", size] = process.argv.slice(2);
  const sizeUsd = size === undefined ? undefined : Number(size);
  if (sizeUsd !== undefined && !(sizeUsd > 0)) throw new Error("The order size must be a positive number of US dollars.");

  const { check, charged, left } = await checkToken(token, sizeUsd);
  const { verdict, confidence, reasons, size_check } = check.data;

  console.log(`${check.data.token.symbol}: ${verdict} (confidence ${confidence}), as of ${check.as_of}`);
  for (const r of reasons) console.log(`  ${r.dimension}: ${r.text} [${r.source}]`);
  if (size_check) console.log(`  order: $${size_check.order_usd}, estimated impact ${size_check.estimated_impact_pct}%`);
  console.log(`Proof: https://coingraph.ai/proof/${check.id}`);
  if (charged) console.log(`Credits: ${charged} charged, ${left} left`);

  // Your agent's decision goes here. Keep the proof id with whatever it does next.
  process.exitCode = verdict === "proceed" ? 0 : 1;
}

main().catch((e: Error) => {
  // Fail closed: if the check can't be completed, the agent shouldn't act as though it passed.
  console.error(`Check not completed: ${e.message}`);
  process.exitCode = 2;
});

claude mcp add --transport http coingraph https://coingraph.ai/mcp

// Your own agent, calling CoinGraph over MCP with an account key.
//
//   npm install @modelcontextprotocol/sdk
//   export COINGRAPH_KEY=cg_live_your_key_here
//   npx tsx agent.ts solana 5000
//
// Listing the tools costs nothing. check_token spends credits at the same prices as the API.
// Claude, Cursor and other AI apps don't need this file or a key: they open a sign-in when you connect them.
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const URL_ = process.env.COINGRAPH_MCP ?? "https://coingraph.ai/mcp";
const KEY = process.env.COINGRAPH_KEY;

async function main() {
  if (!KEY) throw new Error("Create a key at https://coingraph.ai/account/keys, then set COINGRAPH_KEY.");
  const [token = "solana", size = "5000"] = process.argv.slice(2);

  const client = new Client({ name: "my-agent", version: "1.0.0" });
  await client.connect(new StreamableHTTPClientTransport(new URL(URL_), { requestInit: { headers: { Authorization: `Bearer ${KEY}` } } }));
  try {
    const { tools } = await client.listTools();
    console.log(`Connected: ${tools.length} tools available`);

    const result = await client.callTool({ name: "check_token", arguments: { token, size_usd: Number(size) } });
    const text = (result.content as { type: string; text?: string }[]).find((c) => c.type === "text")?.text ?? "";
    if (result.isError) throw new Error(text);

    const check = JSON.parse(text);
    console.log(`${check.data.token.symbol}: ${check.data.verdict} (confidence ${check.data.confidence})`);
    console.log(`Proof: https://coingraph.ai/proof/${check.id}`);
    process.exitCode = check.data.verdict === "proceed" ? 0 : 1;
  } finally {
    await client.close();
  }
}

main().catch((e: Error) => {
  // Fail closed: if the check can't be completed, the agent shouldn't act as though it passed.
  console.error(`Check not completed: ${e.message}`);
  process.exitCode = 2;
});