Developer documentation

Build agents that pay only for what they read.

Rubicon gives buyer agents a budgeted path from content discovery to metered delivery. Start with the SDK for application control, use the CLI for terminal workflows, or import core protocol types directly.

v0.1.4

@rubicon-caliga/agent-sdk

High-level discovery, navigation, paid streaming, and receipts.

View package

v0.1.5

@rubicon-caliga/cli

Terminal-native discovery and budgeted reads for agents.

View package

v0.1.3

@rubicon-caliga/core

Shared protocol types, pricing math, and session primitives.

View package

Quickstart

Run your first budgeted read

Install the SDK, create a client, and pass a hard spend ceiling in atomic USDC. One USDC has 1,000,000 atomic units.

Terminal

npm install @rubicon-caliga/agent-sdk

TypeScript

import Rubicon from "@rubicon-caliga/agent-sdk";

const rubicon = new Rubicon({
  baseUrl: process.env.RUBICON_GATEWAY_URL,
  authorization: `Bearer ${process.env.RUBICON_AGENT_API_KEY}`,
});

const receipt = await rubicon.run({
  articleId: "live-article-id",
  goal: "Find the resale-fee clause",
  maxSpendAtomic: "20000",
  maxWords: 200,
  stopWhen: ({ text }) => /resale fee/i.test(text),
  onWord: (word) => process.stdout.write(`${word} `),
});

console.log(receipt.stopReason, receipt.amountPaidAtomic);

Budget enforcement is part of the read.`maxSpendAtomic`, `maxWords`, and `stopWhen` can all end delivery before the full article is purchased.

Agent SDK

Choose the right level of control

Method	Use it for	Returns
`run(options)`	A complete read with callbacks	`ReadReceipt`
`read(options)`	Handling every event in your own loop	`AsyncGenerator`
`getRepository()`	Discovering public articles	Article summaries
`getNavigation(id, goal)`	Finding the most relevant section	Seller navigation
`abort(sessionId)`	Stopping an active read explicitly	`Promise<void>`

Streaming reads

React to delivery as it happens

read() yields session, seller, content, usage, completion, and error events. Bundled mode is the default and reduces payment round trips without changing per-word accounting.

TypeScript

for await (const event of rubicon.read({
  articleId,
  goal: "Extract the contract termination conditions",
  maxSpendAtomic: "100000",
  chunkWords: 32,
  streamMode: "bundled",
})) {
  if (event.type === "article.bundle") {
    process.stdout.write(event.bundleText);
  }

  if (event.type === "article.completed") {
    console.log(event.receipt.settlementIds);
  }
}

session.startedseller.messagearticle.bundlearticle.usagearticle.completedarticle.error

CLI

Use Rubicon from the terminal

The CLI is the shortest path for coding agents and shell workflows. Add --json when another process will consume the output.

Terminal

npm install --global @rubicon-caliga/cli

rubicon doctor --json
rubicon repository
rubicon search "stablecoin settlement"
rubicon article navigation <article-id> --goal "Find fee terms"
rubicon read <article-id> --max-usdc 0.10 --goal "Find fee terms" --summary

01Discover

List or search public articles.

02Navigate

Ask the seller agent for the best section.

03Read

Set a budget and store the final receipt.

Core primitives

Share contracts across your stack

Use core when implementing gateway integrations, validating accounting, or sharing Rubicon types between services.

TypeScript

import {
  quotePerWord,
  usageForWords,
  settlementNetworkInfo,
  type Budget,
} from "@rubicon-caliga/core";

const quote = quotePerWord({
  pricePerWordAtomic: 10n,
  gatewayFeeBps: 0,
});

const usage = usageForWords({
  wordsDelivered: 137,
  pricePerWordAtomic: 10n,
});

Payment engines

Develop locally, settle through Circle

StaticPaymentEngine

Default development engine for a dev-mode gateway. It declares authorized amounts and does not settle real funds.

CircleCliGatewayPaymentEngine

Signs Circle and Arc authorization payloads through a Circle Agent Wallet without exposing raw private keys to the SDK.

CircleAgentWalletEngine

API-backed custody using Circle Developer-Controlled Wallets. Provision and fund the wallet before starting reads.

TypeScript

import Rubicon, {
  CircleCliGatewayPaymentEngine,
} from "@rubicon-caliga/agent-sdk";

const rubicon = new Rubicon({
  baseUrl: process.env.RUBICON_GATEWAY_URL,
  paymentEngine: new CircleCliGatewayPaymentEngine({
    agentWalletAddress: process.env.CIRCLE_AGENT_WALLET_ADDRESS as `0x${string}`,
    chain: "ARC-TESTNET",
  }),
});

Receipts

Keep settlement evidence

A completed read returns its word count, total paid amount, text, stop reason, and payment evidence. For Gateway nanopayments, treat settlementIds as primary proof; a transaction hash may not exist for every payment.

Persist sessionId and articleId

Store amountPaidAtomic and wordsRead

Index settlementIds for reconciliation

Record stopReason for agent audits

HTTP API

Gateway endpoints

The SDK wraps the public gateway flow. Use the endpoints directly only when building another language client or a custom runtime.

GET/v1/repository

List public articles.

GET/v1/articles/:id/navigation

Ask for goal-aware section routing.

POST/v1/seller-agent/conversations

Start a seller conversation.

POST/v1/sessions

Open a budgeted reading session.