SDK Plugins

Quick Start

import Relai from '@relai-fi/x402/server'
import { freeTier } from '@relai-fi/x402/plugins'

const relai = new Relai({
  network: 'base',
  plugins: [
    freeTier({
      serviceKey: process.env.RELAI_SERVICE_KEY!,
      perBuyerLimit: 5,
      resetPeriod: 'daily',
    }),
  ],
})

app.get('/api/data', relai.protect({
  payTo: '0xYourWallet',
  price: 0.01,
}), (req, res) => {
  if (req.x402Free) {
    // Free tier call — no payment was made
    console.log('Remaining:', req.pluginMeta?.remaining)
  }
  res.json({ data: 'content' })
})

Configuration

Local vs Cloud Mode

Local mode example — no key needed, usage tracked in-memory:

const ft = freeTier({ perBuyerLimit: 3, resetPeriod: 'none' }) // every new caller gets 3 lifetime free calls

const relai = new Relai({ network: 'base', plugins: [ft] })

// Export usage data at any time
app.get('/admin/usage', (req, res) => {
  res.json(ft.getUsageData()) // returns all tracked usage
})

In cloud mode, getUsageData() returns null — use the dashboard instead. You can check which mode is active via ft.mode ('local' or 'cloud').

Buyer Identification

The plugin resolves buyer identity automatically from the request, in priority order:

How It Works

When a request arrives without a payment header, the plugin calls the RelAI backend (POST /v1/plugins/free-tier/check) to see if the buyer has free calls remaining. If yes, the request skips payment and the call is recorded. If not, the normal 402 flow kicks in.

If the request already has a payment header (client is paying), plugins are skipped entirely — payment is processed as usual.

Response Headers

When a request is served via free tier, the following headers are added to the response:

Request Properties

The plugin attaches metadata to the request object so your handler can detect free vs paid calls:

app.get('/api/data', relai.protect({ payTo, price: 0.01 }), (req, res) => {
  if (req.x402Free) {
    // Free tier access
    const remaining = req.pluginMeta?.remaining
    return res.json({ data: '...', freeTier: true, remaining })
  }
  // Paid access
  res.json({ data: '...', payment: req.payment })
})

Quick Start

import Relai from '@relai-fi/x402/server'
import { bridge } from '@relai-fi/x402/plugins'

const relai = new Relai({
  network: 'skale-bite',
  plugins: [
    bridge({
      serviceKey: process.env.RELAI_SERVICE_KEY,
    }),
  ],
})

app.get('/api/data', relai.protect({
  payTo: '0xYourWallet',
  price: 0.05,
}), (req, res) => {
  // Buyers on Solana, SKALE Base, or Base can pay here
  res.json({ data: 'premium content' })
})

That's it. Buyers on Solana, SKALE Base, or Base can now pay for your endpoint.

How It Works

1. Plugin discovers bridge capabilities — on startup, bridge() calls/bridge/info and learns which source chains, wallets, and fees are available.
2. 402 response includes bridge info — when a buyer hits your endpoint without payment, the plugin enriches the 402 response with extensions.bridge containing supported source chains and the settle endpoint.
3. Client detects mismatch — the buyer's wallet is on Solana but the API accepts SKALE. The client SDK sees extensions.bridge and finds Solana as a supported source.
4. Payment routes through bridge — the buyer signs a USDC transfer on their chain. The SDK sends it to /bridge/settle, which settles source and pays out on the target chain.
5. Server trusts bridge proof — the SDK retries the request with an X-PAYMENT header containing bridged: true. The server verifies and lets the request through.

Configuration

Pass your service key to enable per-key bridge analytics in the dashboard. Other options are auto-discovered.

Supported Chains

New chains are added on the backend — the plugin picks them up automatically via /bridge/info. No SDK update needed.

Combining with Free Tier

Bridge works alongside other plugins. Free tier runs first — if the buyer has free calls left, they bypass payment. If not, the 402 includes bridge info so they can pay from any chain.

import Relai from '@relai-fi/x402/server'
import { freeTier, bridge } from '@relai-fi/x402/plugins'

const relai = new Relai({
  network: 'skale-bite',
  plugins: [
    freeTier({
      serviceKey: process.env.RELAI_SERVICE_KEY!,
      perBuyerLimit: 5,
      resetPeriod: 'daily',
    }),
    bridge({
      serviceKey: process.env.RELAI_SERVICE_KEY!,
    }),
  ],
})

Plugin Interface

The PluginContext passed to hooks contains: network, price, path, method.

PluginResult can include: skip (boolean), headers (added to response), meta (attached to req.pluginMeta).

Example: Custom Rate Limit Plugin

import type { RelaiPlugin } from '@relai-fi/x402/plugins'

const rateLimitPlugin: RelaiPlugin = {
  name: 'rate-limit',

  async beforePaymentCheck(req, ctx) {
    const ip = req.ip || req.socket?.remoteAddress || 'unknown'
    const count = await getRequestCount(ip, ctx.path)

    if (count > 100) {
      // Return skip: false (or empty) to require payment
      return {}
    }

    // Under limit — allow free access
    return {
      skip: true,
      headers: { 'X-Rate-Remaining': String(100 - count) },
      meta: { rateLimit: true, remaining: 100 - count },
    }
  },

  async afterSettled(req, result, ctx) {
    // Log paid requests for analytics
    console.log(`Paid $${ctx.price} by ${result.payer} on ${ctx.network}`)
  },

  async onInit() {
    // Called once on first request — setup, sync config, etc.
    console.log('Rate limit plugin initialized')
  },
}