Quickstart

This guide walks you through making your first Relayer API call. You will verify connectivity with the health endpoint, then make an authenticated request.

Prerequisites

An API key from your operator dashboard (see Authentication)
curl or Node.js installed

Environments

Relayer provides two environments. Choose the one that matches your stage:

Environment	Base URL	Use for
Sandbox	`https://testnet.relayer.fi/v1`	Testing and development
Production	`https://api.relayer.fi/v1`	Live operations

Sandbox runs on Render — the first request after idle may take 30-60 seconds to cold-start.

Step 1: Verify connectivity

Start with the unauthenticated root endpoint to confirm the API is reachable.

Sandbox
Production

curl https://testnet.relayer.fi/v1/

const response = await fetch("https://testnet.relayer.fi/v1/");
const data = await response.json();
console.log(data);

curl https://api.relayer.fi/v1/

const response = await fetch("https://api.relayer.fi/v1/");
const data = await response.json();
console.log(data);

You should receive a 200 with a basic service descriptor.

Step 2: Set up your environment

Store your API key and base URL as environment variables:

Sandbox
Production

export RELAYER_BASE_URL="https://testnet.relayer.fi/v1"
export RELAYER_API_KEY="rk_client_key_v1_your_key_here"

RELAYER_BASE_URL=https://testnet.relayer.fi/v1
RELAYER_API_KEY=rk_client_key_v1_your_key_here

export RELAYER_BASE_URL="https://api.relayer.fi/v1"
export RELAYER_API_KEY="rk_client_key_v1_your_production_key"

RELAYER_BASE_URL=https://api.relayer.fi/v1
RELAYER_API_KEY=rk_client_key_v1_your_production_key

Step 3: Make an authenticated request

Now make an authenticated call. This example lists the wallets in your workspace — a safe, read-only operation that confirms auth, scope, and module activation in one go.

curl -X GET $RELAYER_BASE_URL/signing/wallets \
  -H "Authorization: ApiKey $RELAYER_API_KEY" \
  -H "Content-Type: application/json"

const baseUrl = process.env.RELAYER_BASE_URL;
const apiKey = process.env.RELAYER_API_KEY;

const response = await fetch(`${baseUrl}/signing/wallets`, {
  headers: {
    Authorization: `ApiKey ${apiKey}`,
    "Content-Type": "application/json",
  },
});

const result = await response.json();
console.log(JSON.stringify(result, null, 2));

import os, requests

base_url = os.environ["RELAYER_BASE_URL"]
api_key = os.environ["RELAYER_API_KEY"]

response = requests.get(
    f"{base_url}/signing/wallets",
    headers={
        "Authorization": f"ApiKey {api_key}",
        "Content-Type": "application/json",
    },
)
print(response.json())

A successful response looks like:

{
  "success": true,
  "message": "Wallets retrieved",
  "data": [],
  "statusCode": 200,
  "timestamp": "2026-05-15T12:00:00.000Z",
  "path": "/v1/signing/wallets"
}

An empty data array is expected on a fresh workspace. It means the API authenticated your request successfully — you just haven’t created any wallets yet.

Step 4: Explore the Kits

Now that you are authenticated, explore the Kit that matches your use case:

Signing Kit

Create self-custodial wallets and sign transactions with passkeys.

Payout Kit

Set up fiat on/off-ramp rails and manage recipients.

Agent Kit

Ship budget-enforced AI agents that can sign and pay for resources.

Widget Kit

Embed canonical swap, transfer, and crosschain widgets in your app.

Troubleshooting

Problem	Solution
`Connection refused`	Check `RELAYER_BASE_URL` — sandbox: `https://testnet.relayer.fi/v1`, production: `https://api.relayer.fi/v1`
`401 Unauthorized`	Verify your `Authorization` header uses `ApiKey` prefix (not `Bearer`)
`404 Not Found`	Check the endpoint path starts with `/v1/`
Slow first response	Sandbox cold-starts after idle (30-60s). Production does not have this delay.

Get Started

Foundations

Prerequisites

Environments

Step 1: Verify connectivity

Step 2: Set up your environment

Step 3: Make an authenticated request

Step 4: Explore the Kits

Signing Kit

Payout Kit

Agent Kit

Widget Kit

Troubleshooting

​Prerequisites

​Environments

​Step 1: Verify connectivity

​Step 2: Set up your environment

​Step 3: Make an authenticated request

​Step 4: Explore the Kits

Signing Kit

Payout Kit

Agent Kit

Widget Kit

​Troubleshooting

Prerequisites

Environments

Step 1: Verify connectivity

Step 2: Set up your environment

Step 3: Make an authenticated request

Step 4: Explore the Kits

Troubleshooting