Setup Guide

This guide walks you through setting up FareSide to accept x402 payments in your application.

Getting Your API Key

FareSide is currently in private beta. To get access:

1. Join the waitlist or contact us on Telegram
2. Receive your API key - We’ll send you a unique key for the hosted facilitator
3. Configure your integration - Use your key in the facilitator URL

Your facilitator URL will be:

https://facilitator.fareside.com/YOUR_API_KEY

Integration Overview

FareSide works with standard x402 middleware libraries. You don’t need a FareSide-specific SDK  — just point any x402-compatible middleware to the FareSide facilitator.

Supported Middleware

You can also see examples for Go, FastAPI and Flask here.

TypeScript Setup

1. Install Dependencies

npm install hono @hono/node-server @x402/hono @x402/core @x402/evm

2. Configure the Middleware

import { Hono } from "hono";
import { serve } from "@hono/node-server";
import { paymentMiddleware } from "@x402/hono";
import { x402ResourceServer, HTTPFacilitatorClient } from "@x402/core/server";
import { registerExactEvmScheme } from "@x402/evm/exact/server";

const app = new Hono();

// Setup Facilitator Client
const facilitatorClient = new HTTPFacilitatorClient({
  url: `https://facilitator.fareside.com/${process.env.FARESIDE_API_KEY}`
});

// Your wallet address for receiving payments
const receiverAddress = process.env.RECEIVER_ADDRESS!;

// Setup Resource Server
const server = new x402ResourceServer(facilitatorClient);
registerExactEvmScheme(server);

// Configure Middleware
app.use(paymentMiddleware(
  {
    "GET /api/premium": {
      accepts: [{
        scheme: "exact",
        price: "$0.10",
        network: "eip155:8453", // Base Mainnet
        payTo: receiverAddress,
      }],
      description: "Premium API access",
    },
    "GET /api/data": {
      accepts: [{
        scheme: "exact",
        price: "$0.01",
        network: "eip155:8453",
        payTo: receiverAddress,
      }],
      description: "Regular data",
    }
  },
  server
));

// Your protected routes
app.get("/api/premium", (c) => c.json({ data: "Premium content" }));
app.get("/api/data", (c) => c.json({ data: "Regular data" }));

serve({ fetch: app.fetch, port: 3000 });

3. Environment Variables

Create a .env file:

# Your wallet address for receiving payments
RECEIVER_ADDRESS=0xYourWalletAddress

# Your FareSide API key
FARESIDE_API_KEY=YourApiKeyHere

Rust Setup

1. Add Dependencies

[dependencies]
alloy-primitives = "1.4"
axum = "0.8"
serde_json = "1"
tokio = "1"
x402-axum = "1.1"
x402-chain-eip155 = { version = "1.1", features = ["server"] }
x402-types = "1.1"

2. Configure the Middleware

use alloy_primitives::Address;
use axum::{routing::get, Json, Router};
use std::env;
use std::str::FromStr;
use x402_axum::X402Middleware;
use x402_chain_eip155::{KnownNetworkEip155, V2Eip155Exact};
use x402_types::networks::USDC;

#[tokio::main]
async fn main() {
    let api_key = env::var("FARESIDE_API_KEY").expect("FARESIDE_API_KEY required");
    let receiver_str = env::var("RECEIVER_ADDRESS").expect("RECEIVER_ADDRESS required");
    let receiver = Address::from_str(&receiver_str).expect("Invalid address");
    
    // Configure FareSide facilitator
    let facilitator_url = format!("https://facilitator.fareside.com/{}", api_key);
    let x402 = X402Middleware::try_from(facilitator_url.as_str()).unwrap();
    
    let usdc = USDC::base();

    let app = Router::new()
        // Protected route with $0.10 price
        .route(
            "/api/premium",
            get(premium_handler).layer(
                x402.with_price_tag(
                    V2Eip155Exact::price_tag(
                        receiver,
                        usdc.amount(100_000u64), // 0.10 USDC (6 decimals)
                    )
                )
                .with_description("Premium API access".to_string()),
            ),
        )
        // Protected route with $0.01 price
        .route(
            "/api/data",
            get(data_handler).layer(
                x402.with_price_tag(
                    V2Eip155Exact::price_tag(
                        receiver,
                        usdc.amount(10_000u64), // 0.01 USDC
                    )
                )
                .with_description("Regular data".to_string()),
            ),
        );

    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

async fn premium_handler() -> Json<serde_json::Value> {
    Json(serde_json::json!({ "data": "Premium content" }))
}

async fn data_handler() -> Json<serde_json::Value> {
    Json(serde_json::json!({ "data": "Regular data" }))
}

3. Environment Variables

export RECEIVER_ADDRESS=0xYourWalletAddress
export FARESIDE_API_KEY=YourApiKeyHere

Wallet Address

To receive x402 payments, you just need a wallet address. No special wallet type or configuration is required.

You can get an address however you prefer:

• Browser wallets - MetaMask, Zerion, Rainbow, Coinbase Wallet
• Hardware wallets - Ledger, Trezor
• CLI-generated - Using cast wallet new or similar tools
• Any other method - The address just needs to be valid for the target network

For EVM networks, use an Ethereum-compatible address (0x…). For Solana, use a Solana public key. No private keys are needed on your server, only the public address where you want to receive funds.

Testing Your Integration

1. Start Your Server

# TypeScript
npx tsx server.ts

# Rust
cargo run

2. Test Without Payment

curl -i http://localhost:3000/api/data

Expected response (402 Payment Required):

HTTP/1.1 402 Payment Required
Payment-Required: eyJ4NDAyVmVyc2lvbiI6MiwiZXJyb3IiOiJQYXltZW50LVNpZ25hdHVyZSBoZWF...
Content-Type: application/json
...

The Payment-Required header contains the base64-encoded JSON object. Decoded, it looks like this:

{
  "x402Version": 2,
  "error": "Payment-Signature header is required",
  "resource": {
    "url": "http://localhost:3000/api/data",
    "description": "Regular data",
    "mimeType": "application/json"
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "amount": "10000",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "payTo": "0xYourWalletAddress",
      "maxTimeoutSeconds": 300,
      "extra": {
        "name": "USD Coin",
        "version": "2"
      }
    }
  ]
}

3. Test With Payment

Use an x402 client to make actual payments. See Making Payments for client setup.

Troubleshooting

• Check your API key is correct
• Verify network connectivity to facilitator.fareside.com
• Ensure you’re using a supported network
• Check CAIP-2 network ID spelling (e.g., eip155:8453)
• Verify the payment amount matches the price
• Ensure the transaction is confirmed on-chain
• Contact support if issues persist

Next Steps

• Express/Hono/Next.js - Detailed TypeScript examples
• Rust (Axum) - Detailed Rust examples
• Self-Hosting - Run your own facilitator