SDK Documentation

RelAI SDK

Official SDK for RelayAI - Monetize any API endpoint with x402 micropayments

The RelAI SDK provides a simple and powerful way to consume paid APIs from the RelAI marketplace. Support for Solana networks with automatic payment verification and settlement.

Installation

Install the SDK using npm or yarn:

Terminal

npm install relai-sdk

Quick Start

Basic example of consuming a paid API from RelAI marketplace:

example.ts

import { RelaiClient } from 'relai-sdk/client'

const client = new RelaiClient({
  network: 'solana',
  wallet: {
    address: publicKey.toString(),
    signTransaction: async (tx) => await signTransaction(tx)
  }
})

const api = client.useApi('your-api-id')
const response = await api.call({
  path: '/api/endpoint',
  method: 'POST',
  body: { prompt: 'Hello' }
})

x402 Client

The RelaiClient handles payment verification and settlement automatically. It intercepts 402 Payment Required responses from RelAI marketplace APIs and processes payments transparently.

Tip: The client automatically handles payment verification, transaction signing, and settlement with the facilitator.

Payment Flow

Client makes request to protected API endpoint
Server returns 402 Payment Required with payment details
SDK verifies payment requirements with facilitator
User signs transaction with their wallet
SDK settles payment with facilitator
Original request is retried with payment proof
Server validates payment and returns protected resource

new RelaiClient(config)

Creates a new RelAI client instance.

interface RelaiClientConfig {
  baseUrl?: string;                    // Default: 'https://relai.fi'
  network?: 'solana' | 'solana-devnet';
  rpcUrl?: string;
  maxPaymentAmount?: bigint;           // Max payment in lamports
  wallet?: {
    address: string;
    signTransaction: (tx: any) => Promise<any>;
  };
  requestTimeoutMs?: number;
  
  // Optional hooks
  onPaymentRequired?: (info) => void;
  onPaymentVerified?: (info) => void;
  onError?: (error) => void;
}

client.useApi(apiId)

Returns a lightweight API helper bound to a specific apiId from RelAI marketplace.

const api = client.useApi(apiId);

const response = await api.call({
  path: '/api/your-endpoint',
  method: 'GET' | 'POST' | 'PUT' | 'DELETE',
  body?: any,
  headers?: Record<string, string>
});

console.log(response.data);

Get Your API ID

To use an API from RelAI marketplace:

Browse the RelAI marketplace
Find an API you want to use
Copy the apiId from the API details page
No registration or API keys required!

Tip: You can start using any API from the marketplace immediately - just copy the apiId and use it with RelaiClient.

Solana Example

import { useWallet } from '@solana/wallet-adapter-react'
import { RelaiClient } from 'relai-sdk/client'

function MyComponent() {
  const wallet = useWallet()
  
  const client = new RelaiClient({
    network: 'solana',
    wallet: {
      address: wallet.publicKey?.toString() || '',
      signTransaction: async (tx) => await wallet.signTransaction(tx)
    }
  })

  const fetchData = async () => {
    const api = client.useApi('your-api-id')
    const response = await api.call({
      path: '/api/endpoint',
      method: 'POST',
      body: { query: 'data' }
    })
    return response.data
  }
}

Solana Devnet Example

For testing, you can use Solana Devnet:

import { RelaiClient } from 'relai-sdk/client'

const client = new RelaiClient({
  network: 'solana-devnet',
  rpcUrl: 'https://api.devnet.solana.com',
  wallet: {
    address: publicKey.toString(),
    signTransaction: async (tx) => await signTransaction(tx)
  }
})

const api = client.useApi('test-api-id')
const response = await api.call({
  path: '/api/test',
  method: 'GET'
})

Payment Lifecycle Hooks

Monitor payment events with lifecycle hooks:

import { RelaiClient } from 'relai-sdk/client'

const client = new RelaiClient({
  network: 'solana',
  wallet: { /* ... */ },
  
  // Payment lifecycle hooks
  onPaymentRequired: (info) => {
    console.log('Payment required:', info.price, info.description)
  },
  onPaymentVerified: (info) => {
    console.log('Payment verified:', info.signature)
  },
  onError: (error) => {
    console.error('Payment error:', error)
  }
})

Tip: Use hooks to show payment status to users, handle errors gracefully, and track payment analytics.

Error Handling

Handle errors gracefully:

try {
  const api = client.useApi('your-api-id')
  const response = await api.call({
    path: '/api/endpoint',
    method: 'POST',
    body: { data: 'value' }
  })
  console.log(response.data)
} catch (error) {
  if (error.message?.includes('insufficient funds')) {
    console.error('Not enough balance for payment')
  } else if (error.message?.includes('rejected')) {
    console.error('User rejected transaction')
  } else {
    console.error('API call failed:', error)
  }
}

SDK GitHub Main Docs Facilitator Twitter