Getting Started

Quickstart

Get your first HoodLayer payment working in under ten minutes.

There are two common ways into HoodLayer, and this guide covers both: paying for a service as an agent, and accepting payments as a service provider. Follow whichever path matches your situation, or do both.

Prerequisites

  • Node.js 18 or newer
  • A Robinhood Chain wallet (either a private key you hold, or an embedded wallet library such as Privy or Dynamic)
  • Some USDC on Robinhood Chain mainnet (testnet USDC works for testing)
  • A HoodLayer API key; request one at hoodlayer.org

Path A: Agent making a payment

1. Install the SDK

npm install @hoodlayerorg/sdk

2. Initialize the agent

import { HoodLayerAgent } from "@hoodlayerorg/sdk";
import { privateKeyToAccount } from "viem/accounts";

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

const agent = new HoodLayerAgent({
  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 USDC (6 decimals)
});

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

The whole x402 flow happens inside agent.pay(). The method reads the server’s 402 response, signs the USDC transfer through the Facilitator, then retries the original request with a payment proof header attached.

4. Subscribe to a plan

When a service publishes a subscription plan, subscribing usually works out 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 that, the service checks your subscription on every request by itself. Renewals happen on-chain and need nothing from you.

Path B: Service provider accepting payments

1. Install the SDK

npm install @hoodlayerorg/sdk

2. Initialize the provider

import { HoodLayerProvider } from "@hoodlayerorg/sdk";
import { privateKeyToAccount } from "viem/accounts";

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

const hoodlayer = new HoodLayerProvider({
  wallet: providerAccount,
  apiKey: process.env.HOODLAYER_API_KEY,
  network: "mainnet",
});

3. Create a plan

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

console.log(plan.id); // save this, it's your plan's on-chain id

4. Add the payment gate to your API

Unauthenticated requests get intercepted by the paymentGate middleware, which answers with a correctly formatted 402 response. Requests carrying a valid subscription or payment proof go straight through.

import express from "express";

const app = express();

// Put the whole /api/v1 namespace behind the gate
app.use("/api/v1", hoodlayer.paymentGate({
  pricing: [
    { type: "subscription", plan: plan.id },
    {
      type: "one-time",
      amount: 500_000, // fallback price of 0.50 USDC per call
    },
  ],
}));

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

5. Collect from active subscribers

Collection can run automatically through HoodLayer’s webhooks and automations, or you can invoke it yourself, say from a cron job.

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

Next steps