Quickstart

An Opus Protocol transaction has two sides: an agent that pays for a service and a provider that charges for it. This guide covers both. Follow the path for your role, or do both to watch a complete round trip.

Prerequisites

• Node.js version 18 or newer
• A wallet on Robinhood Chain, either a private key you hold or an embedded wallet library like Privy or Dynamic
• Some USDG on Robinhood Chain mainnet (or testnet USDG while you experiment)
• An Opus Protocol API key, which you can request at opusprotocol.org

Path A: An agent paying for a service

1. Add the SDK

npm install @opusprotocol/sdk

2. Set up the agent

import { OpusProtocolAgent } from "@opusprotocol/sdk";
import { privateKeyToAccount } from "viem/accounts";

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

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

3. Send 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

One call to agent.pay() performs the whole x402 exchange. It reads the 402 response from the server, signs the USDG transfer via the Facilitator, and sends the original request a second time, carrying a payment proof header. The transaction hash that comes back is your receipt, recorded on the chain.

4. Start a subscription

If you call a service often, a subscription is usually cheaper than paying per request. All you need is 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"

After this, the service checks your subscription on every request with no action on your part, and renewals settle on-chain on their own.

Path B: A provider charging for a service

1. Add the SDK

npm install @opusprotocol/sdk

2. Set up the provider

import { OpusProtocolProvider } from "@opusprotocol/sdk";
import { privateKeyToAccount } from "viem/accounts";

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

const opusprotocol = new OpusProtocolProvider({
  wallet: providerAccount,
  apiKey: process.env.OPUSPROTOCOL_API_KEY,
  network: "mainnet",
});

3. Create a plan

const plan = await opusprotocol.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. Put the payment gate in front of your API

The paymentGate middleware catches requests that carry no authentication and answers them with a well-formed 402 response. Requests that include a valid subscription or payment proof go through unchanged.

import express from "express";

const app = express();

// Gate the entire /api/v1 namespace
app.use("/api/v1", opusprotocol.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 payments from subscribers

You can let Opus Protocol’s webhooks and automations handle collection, or you can call it yourself, for example from a cron job.

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

Next steps

• Plans covers plan pricing and why plans are immutable
• Subscriptions walks through the billing lifecycle
• Webhooks pushes subscription events to your systems as they happen
• Every method is listed in the Agent SDK and Provider SDK references