Agent SDK

Installation

npm install @scribefinance/sdk

ScribeFinanceAgent

import { ScribeFinanceAgent } from "@scribefinance/sdk";

const agent = new ScribeFinanceAgent(config: ScribeFinanceAgentConfig);

ScribeFinanceAgentConfig

Option	Type	Required	Description
`wallet`	`Signer`	Yes	A viem account, ethers wallet, or any compatible signer
`network`	`"mainnet" \\| "testnet"`	Yes	The Robinhood Chain network to operate on
`rpcUrl`	`string`	No	Custom Robinhood Chain RPC endpoint
`facilitatorUrl`	`string`	No	Alternate Facilitator URL (default: Scribe Finance’s hosted Facilitator)
`defaultToken`	`string`	No	Default token address (default: USDG)

Wallets

wallet accepts either of two shapes:

A viem local account or an ethers wallet
Any object satisfying the Signer interface: { address: Address, signTypedData(typedData): Promise<string> }

The practical consequence: embedded wallet signers from Privy, Dynamic, Turnkey, and similar providers plug in directly.

// viem local account
import { privateKeyToAccount } from "viem/accounts";
const account = privateKeyToAccount(process.env.WALLET_PRIVATE_KEY as `0x${string}`);
const agent = new ScribeFinanceAgent({ wallet: account, network: "mainnet" });

// embedded wallet from Privy
const agent = new ScribeFinanceAgent({ wallet: privySigner, network: "mainnet" });

Methods

agent.pay()

Executes a one-time payment over the x402 flow. The full request-402-pay-retry cycle runs inside this single call.

const result = await agent.pay(options: PayOptions): Promise<PayResult>

PayOptions

Option	Type	Required	Description
`url`	`string`	Yes	URL of the resource being paid for
`method`	`string`	No	HTTP verb (default: `"GET"`)
`body`	`object`	No	Request body for POST requests
`headers`	`object`	No	Additional request headers
`maxAmount`	`number`	No	Spending ceiling in token base units; the call rejects if the service charges above it
`token`	`string`	No	Token address to pay with (default: USDG)

PayResult

Field	Type	Description
`data`	`any`	Parsed response body from the API
`status`	`number`	HTTP status code of the response
`headers`	`object`	Response headers
`txHash`	`string`	Robinhood Chain transaction hash
`amountPaid`	`number`	Amount actually paid, in token base units

const result = await agent.pay({
  url: "https://api.example.com/v1/data",
  maxAmount: 1_000_000, // reject any charge above 1 USDG
});

console.log(result.data);   // the response body
console.log(result.txHash); // the payment, written to the chain

agent.subscribe()

Creates an on-chain subscription to a plan, delegating billing authority to the service provider.

const sub = await agent.subscribe(options: SubscribeOptions): Promise<Subscription>

SubscribeOptions

Option	Type	Required	Description
`planId`	`string`	Yes	On-chain id of the plan
`maxOveragePerCycle`	`number`	No	Ceiling on metered overage spend per cycle
`token`	`string`	No	Pay in a token other than the plan’s default

Returns: a Subscription object; its full shape lives in Subscriptions.

const sub = await agent.subscribe({
  planId: "0x7f3a...plan_id",
  maxOveragePerCycle: 10_000_000, // allow overage up to 10 USDG
});

console.log(sub.id);            // id of the subscription record on-chain
console.log(sub.status);        // either "ACTIVE" or "TRIAL"
console.log(sub.nextBillingAt); // a Unix timestamp

agent.cancelSubscription()

Terminates an active subscription. The cancellation is written to the chain and applies immediately.

await agent.cancelSubscription(options: { subscriptionId: string }): Promise<void>

agent.listSubscriptions()

Returns all subscriptions associated with the agent’s wallet.

const subs = await agent.listSubscriptions(
  options?: { status?: SubscriptionStatus }
): Promise<Subscription[]>

agent.createAllowance()

Establishes a metered spend cap. See Allowances for the full model.

const allowance = await agent.createAllowance(options: AllowanceOptions): Promise<Allowance>

AllowanceOptions

Option	Type	Required	Description
`grantee`	`string`	Yes	Service wallet address being granted spend authority
`maxAmount`	`number`	Yes	Total spend cap, in token base units
`token`	`string`	No	Token contract to use (default: USDG)
`expiresAt`	`number`	No	Expiry as a Unix timestamp

agent.revokeAllowance()

Withdraws an allowance ahead of its expiry.

await agent.revokeAllowance(options: { allowanceId: string }): Promise<void>

agent.getAllowance()

Returns an allowance’s current state.

const status = await agent.getAllowance(
  options: { allowanceId: string }
): Promise<Allowance>

Error handling

The SDK throws a typed error for every failure mode:

import {
  InsufficientFundsError,
  PaymentRejectedError,
  AllowanceExhaustedError,
  FacilitatorError,
} from "@scribefinance/sdk/errors";

try {
  await agent.pay({ url: "...", maxAmount: 1_000_000 });
} catch (e) {
  if (e instanceof InsufficientFundsError) {
    console.error("Wallet needs more USDG", e.required, e.available);
  } else if (e instanceof PaymentRejectedError) {
    console.error("Service rejected payment proof", e.reason);
  } else if (e instanceof FacilitatorError) {
    console.error("Facilitator error", e.statusCode, e.message);
  }
}

Error class	Cause
`InsufficientFundsError`	The wallet balance is below the required amount
`PaymentRejectedError`	The service declined the payment proof
`MaxAmountExceededError`	The service’s price exceeded `maxAmount`
`AllowanceExhaustedError`	The spend cap is fully consumed
`SubscriptionNotActiveError`	The subscription is paused or cancelled
`FacilitatorError`	The Facilitator returned an error
`ChainTransactionError`	The transaction failed on-chain