Getting Started

Quickstart

Make your first payment with Recur Protocol in under ten minutes.

This guide walks through the two most common entry points: making a payment as an agent, and accepting payments as a service provider. You can follow one or both depending on your use case.

Prerequisites

  • Node.js 18 or later
  • A Solana wallet (a keypair file or a library like Privy or Dynamic for embedded wallets)
  • USDC on Solana mainnet (or devnet USDC for testing)
  • A Recur API key — request one at recurprotocol.com

Path A: Agent making a payment

1. Install the SDK

npm install @recur/sdk

2. Initialize the agent

import { RecurAgent } from "@recur/sdk";
import { Keypair } from "@solana/web3.js";
import fs from "fs";

const keypair = Keypair.fromSecretKey(
  Uint8Array.from(JSON.parse(fs.readFileSync("./wallet.json", "utf-8")))
);

const agent = new RecurAgent({
  wallet: keypair,
  network: "mainnet-beta",
});

3. Make a one-time payment

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

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

agent.pay() handles the full x402 flow automatically. It reads the 402 response from the server, signs the USDC transfer via the Facilitator, and retries the original request with a payment proof header attached.

4. Subscribe to a plan

If the service offers a subscription plan, subscribing is more economical than paying per request. You only need the plan’s on-chain address.

const subscription = await agent.subscribe({
  planId: "7xKp...plan_address_here",
});

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

Once subscribed, the service automatically verifies your subscription on each request. Billing renews on-chain without any action from you.

Path B: Service provider accepting payments

1. Install the SDK

npm install @recur/sdk

2. Initialize the provider

import { RecurProvider } from "@recur/sdk";
import { Keypair } from "@solana/web3.js";

const recur = new RecurProvider({
  wallet: providerKeypair,
  apiKey: process.env.RECUR_API_KEY,
  network: "mainnet-beta",
});

3. Create a plan

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

console.log(plan.id); // store this — it's your on-chain plan address

4. Add the payment gate to your API

The paymentGate middleware intercepts unauthenticated requests and returns a properly formatted 402 response. Authenticated requests (valid subscription or payment proof) pass through.

import express from "express";

const app = express();

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

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

5. Collect from active subscribers

Recur can trigger collection automatically through webhooks and automations, but you can also call it directly — for example, from a cron job.

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

Next steps