Merchants • 5 min read

Setup Guide

Get your FareSide API key and configure your integration

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 at fareside.com 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

FrameworkLibraryPackage
Honox402-hononpm
Expressx402-expressnpm
Next.jsx402-nextnpm
Axumx402-axumcrates.io

TypeScript Setup

1. Install Dependencies

npm install hono x402-hono

2. Configure the Middleware

import { Hono } from "hono";
import { serve } from "@hono/node-server";
import { paymentMiddleware } from "x402-hono";

const app = new Hono();

// Configure x402 middleware with FareSide facilitator
app.use(paymentMiddleware(
  process.env.RECEIVER_ADDRESS!,  // Your wallet address
  {
    // Define which routes require payment
    "/api/premium": {
      price: "$0.10",
      network: "base",
      config: {
        description: "Premium API access",
      }
    },
    "/api/data": {
      price: "$0.01", 
      network: "base",
    }
  },
  {
    // Point to FareSide facilitator
    url: `https://facilitator.fareside.com/${process.env.FARESIDE_API_KEY}`,
  }
));

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

app.get("/api/data", (c) => {
  return 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=your_api_key_here

Rust Setup

1. Add Dependencies

[dependencies]
axum = "0.7"
tokio = { version = "1", features = ["full"] }
x402-axum = "0.1"

2. Configure the Middleware

use axum::{routing::get, Router, Json};
use x402_axum::{X402Middleware, USDCDeployment, Network};
use std::env;

#[tokio::main]
async fn main() {
    let api_key = env::var("FARESIDE_API_KEY").expect("FARESIDE_API_KEY required");
    let receiver = env::var("RECEIVER_ADDRESS").expect("RECEIVER_ADDRESS required");
    
    // 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 = USDCDeployment::by_network(Network::Base);

    let app = Router::new()
        // Protected route with $0.10 price
        .route("/api/premium", get(premium_handler).layer(
            x402.with_price_tag(
                usdc.amount("0.10")
                    .pay_to(&receiver)
                    .unwrap()
            )
        ))
        // Protected route with $0.01 price
        .route("/api/data", get(data_handler).layer(
            x402.with_price_tag(
                usdc.amount("0.01")
                    .pay_to(&receiver)
                    .unwrap()
            )
        ));

    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=your_api_key_here

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 http://localhost:3000/api/data

Expected response (402 Payment Required for base network):

{
  "error": "X-PAYMENT header is required",
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "maxAmountRequired": "10000",
      "resource": "http://localhost:3000/api/data",
      "payTo": "0xYourWalletAddress",
      "maxTimeoutSeconds": 300,
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "extra": {
        "name": "USD Coin",
        "version": "2"
      }
    }
  ],
  "x402Version": 1
}

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 network name spelling (e.g., “base” not “Base”)
  • Verify the payment amount matches the price
  • Ensure the transaction is confirmed on-chain
  • Contact support if issues persist

Next Steps