Getting Started

Quickstart

From zero to a settled Scribe Finance payment in about ten minutes.

This guide walks both sides of a Scribe Finance transaction: an agent paying for a service, and a provider charging for one. Take the path that fits your role, or run through both to see the full round trip.

Prerequisites

  • Node.js 18 or later
  • A Robinhood Chain wallet: a private key you control, or an embedded wallet library such as Privy or Dynamic
  • USDG on Robinhood Chain mainnet (testnet USDG is fine while you experiment)
  • A Scribe Finance API key, available on request at scribefinance.org

Path A: Agent making a payment

1. Install the SDK

npm install @scribefinance/sdk

2. Initialize the agent

import { ScribeFinanceAgent } from "@scribefinance/sdk";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.WALLET_PRIVATE_KEY as `0x${string}`);

const agent = new ScribeFinanceAgent({
  wallet: account,
  network: "mainnet",
});

3. Make a one-time payment

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

console.log(result.data);   // the API response
console.log(result.txHash); // on-chain proof

A single call to agent.pay() runs the entire x402 exchange: it parses the server’s 402 response, signs the USDG transfer through the Facilitator, and replays the original request with a payment proof header. The transaction hash it returns is your receipt, written to the chain.

4. Subscribe to a plan

For a service you call regularly, a subscription typically beats per-request pricing, and it takes nothing more than the plan’s on-chain id.

const subscription = await agent.subscribe({
  planId: "0x7f3a...plan_id_here",
});

console.log(subscription.id);     // on-chain subscription id
console.log(subscription.status); // "ACTIVE"

From here the service verifies your subscription on each request without your involvement, and renewals settle on-chain automatically.

Path B: Service provider accepting payments

1. Install the SDK

npm install @scribefinance/sdk

2. Initialize the provider

import { ScribeFinanceProvider } from "@scribefinance/sdk";
import { privateKeyToAccount } from "viem/accounts";

const providerAccount = privateKeyToAccount(process.env.WALLET_PRIVATE_KEY as `0x${string}`);

const scribefinance = new ScribeFinanceProvider({
  wallet: providerAccount,
  apiKey: process.env.SCRIBEFINANCE_API_KEY,
  network: "mainnet",
});

3. Create a plan

const plan = await scribefinance.createPlan({
  name: "API Pro (10k calls/month)",
  amount: 49_000_000, // 49 USDG
  interval: "MONTHLY",
  trialPeriodDays: 7,
});

console.log(plan.id); // record this: it is the plan's on-chain id

4. Add the payment gate to your API

The paymentGate middleware intercepts unauthenticated requests and returns a properly formed 402 response. A request bearing a valid subscription or payment proof passes through untouched.

import express from "express";

const app = express();

// Gate the entire /api/v1 namespace
app.use("/api/v1", scribefinance.paymentGate({
  pricing: [
    { type: "subscription", plan: plan.id },
    {
      type: "one-time",
      amount: 500_000, // 0.50 USDG per call as the fallback price
    },
  ],
}));

app.get("/api/v1/data", (req, res) => {
  res.json({ result: "your data here" });
});

5. Collect from active subscribers

Scribe Finance’s webhooks and automations can drive collection for you, or you can trigger it directly, from a cron job, for instance.

await scribefinance.collectAll({ plan: plan.id });

Next steps