SDK Plugins

Extend x402 payments with logic — without touching your backend.

Add free tiers, cross-chain payments, abuse protection, and analytics in a few lines of code.

5-line example

server.ts

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

const relai = new Relai({
  network: "base",
  plugins: [
    freeTier({ perBuyerLimit: 5 }),
    bridge(),
  ],
})

First 5 calls are free. After that — pay per request. From any chain.

What plugins can do

Plugins run before or after payment. They can:

Skip payment

Free tier — first N calls allowed without paying

Reject requests

Shield/Preflight — protect buyers from broken or unhealthy endpoints

Enable cross-chain

Bridge — accept payment from any supported network

Record data

Score/Feedback — track usage and build on-chain reputation

How plugins work

RequestPlugins (before)PaymentPlugins (after)Response

01 — Request arrives at your endpoint

02 — Before-payment plugins run (can skip or block)

03 — Payment is required or skipped

04 — Payment settles on-chain

05 — After-payment plugins run (analytics, reputation)

Common setups

Free trial API

First calls are free — then x402 kicks in.

server.ts

freeTier({ perBuyerLimit: 5 })

// First 5 requests per buyer → free
// From request 6 onwards → payment required

Cross-chain payments

Users can pay from any supported chain.

server.ts

bridge()

// Server is on SKALE Base
// Buyers can pay from Solana, Base, or SKALE Base

Abuse protection

Block failing or abusive requests before payment is charged.

server.ts

shield({ healthUrl: "https://api.example.com/health" })
preflight({ maxFails: 3 })
circuitBreaker({ windowMs: 60000 })

Analytics & reputation

server.ts

feedback()  // track usage + EVM reputation
score()    // on-chain reputation score (SAPI)

Combined: free tier + bridge

server.ts

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! }),
  ],
})

Free Tier Plugin

Allow a configurable number of free requests per buyer before requiring payment. Buyers are identified by JWT, API key, or IP address.

server.ts

freeTier({
  serviceKey: process.env.RELAI_SERVICE_KEY!,
  perBuyerLimit: 5,        // free calls per buyer
  resetPeriod: "daily",    // none | daily | weekly | monthly
  globalCap: 1000,         // optional: total free calls across all buyers
})

Option	Type	Description
serviceKey	string	RelAI service key for quota tracking
perBuyerLimit	number	Free requests allowed per buyer
resetPeriod	none \| daily \| weekly \| monthly	When the quota resets
globalCap	number?	Total free calls across all buyers
buyerIdHeader	string?	Custom header for buyer identification

Access free tier state in your handler via req.x402Free and req.pluginMeta?.remaining.

Bridge Plugin

Accept payments from multiple source chains while your API settles on one target chain. Buyers on Solana, SKALE Base, or Base can pay to an endpoint on SKALE BITE V2 — automatically.

server.ts

bridge({
  serviceKey: process.env.RELAI_SERVICE_KEY,
})

Supported bridge pairs

Solana → SKALE BITE V2

SKALE Base → SKALE BITE V2

Base → SKALE BITE V2

Shield Plugin

Check your API's health before allowing payment. If the endpoint is down, buyers get a 503 instead of paying for a broken response.

server.ts

shield({
  healthUrl: "https://api.example.com/health",
  timeoutMs: 3000,
})

Preflight Plugin

Track buyer failure rates. After a configurable number of failed paid requests, block the buyer from retrying. Protects against abuse and repeated failed payments.

server.ts

preflight({
  maxFails: 3,        // block after 3 failures
  windowMs: 60000,     // within 60 seconds
})

Circuit Breaker Plugin

Automatically open the circuit (reject all paid requests) when error rates exceed a threshold. Closes again after a cooldown period.

server.ts

circuitBreaker({
  windowMs: 60000,        // evaluation window
  errorThreshold: 0.5,    // 50% error rate triggers open
  cooldownMs: 30000,      // wait before retrying
})

Refund Plugin

Automatically trigger a refund if your handler throws an error after payment. Ensures buyers are never charged for failed responses.

server.ts

refund({
  serviceKey: process.env.RELAI_SERVICE_KEY!,
  onError: true, // refund on 5xx responses
})

Reputation (ERC-8004)

Track API usage and build on-chain reputation for buyers. Integrates with SAPI for Solana and EVM-based reputation scoring.

score()

Records a payment interaction and updates the buyer's on-chain reputation score.

server.ts

score({
  serviceKey: process.env.RELAI_SERVICE_KEY!,
})

feedback()

Submits signed feedback after each interaction. Supports EVM and Solana.

server.ts

feedback({
  serviceKey: process.env.RELAI_SERVICE_KEY!,
})

Custom plugins

Implement the plugin interface to add any logic to the payment flow.

my-plugin.ts

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

const myPlugin = (): RelaiPlugin => ({
  name: "my-plugin",

  async beforePayment({ req, res, next, skip }) {
    // called before 402 is returned
    // call skip() to bypass payment entirely
    next()
  },

  async afterPayment({ req, res, next, txHash }) {
    // called after successful settlement
    next()
  },
})

Reference

All available plugins and their imports:

Plugin	Import	Purpose
freeTier()	@relai-fi/x402/plugins	Allow N free requests per buyer
bridge()	@relai-fi/x402/plugins	Accept payment from multiple source chains
shield()	@relai-fi/x402/plugins	Health-check before allowing payment
preflight()	@relai-fi/x402/plugins	Block buyers with repeated failures
circuitBreaker()	@relai-fi/x402/plugins	Auto-open circuit on high error rate
refund()	@relai-fi/x402/plugins	Auto-refund on handler error
score()	@relai-fi/x402/plugins	EVM on-chain reputation scoring
feedback()	@relai-fi/x402/plugins	Submit signed interaction feedback
solanaFeedback()	@relai-fi/x402/plugins	Solana SAPI reputation feedback

Environment variables

RELAI_SERVICE_KEY=your-service-key  # required for freeTier, bridge, refund, score, feedback
RELAI_API_URL=https://api.relai.fi         # optional: custom API endpoint

SDK reference Facilitator docs Networks