Getting Started - Relayer.fi

This is the full path from “I just heard about Relayer” to “my agent is running, spending USDC, and tracked by 3-layer budget enforcement”. Roughly 30 minutes if you have your wallet funded.

1. Create a workspace

Sign up at the Relayer dashboard with your email. You’ll receive a verification link; once confirmed, you land in your workspace — the multi-tenant container that holds your wallets, API keys, team, and agents.A workspace is free to create. Billing kicks in only when you activate a Kit module that has paid usage (Payouts) or when your agents start spending.

2. Register a passkey

The dashboard walks you through registering a passkey on your device (Face ID, Touch ID, Windows Hello, or a hardware security key). The passkey is the only thing that can authorize signing operations on your wallets — neither Relayer nor your password can.You can register more than one passkey per workspace (recommended: one per device + one hardware key for recovery).

3. Activate the Agent Kit module

In Dashboard → Modules, toggle Agent Kit on. This:

Enables the /v1/agents/* endpoints for your workspace
Provisions an internal queue for budget enforcement
Activates the agent permission scope on your API keys

You can also activate Signing Kit (required for any wallet operations), Payout Kit (fiat rails), and Widget Kit (embedded UI) independently. Agent Kit depends on Signing Kit — the dashboard activates both if needed.

4. Generate an API key

In Dashboard → API Keys, click Create key. Pick scope integrator (read+write) or integrator:write (write only) and give it a name (e.g. “agent-provisioning-prod”).The key is shown once — rk_client_key_v1_.... Save it in your password manager or secret store; you can’t retrieve it later, only revoke and re-issue.

Never commit API keys to version control. Use environment variables or a secret manager (Vercel envs, AWS Secrets Manager, Doppler, etc.).

5. Create your operator wallet (if you don't have one)

The agent’s USDC funds come from your operator wallet — a self-custodial wallet your workspace owns. Create it from the dashboard’s Wallets tab (wallet creation is passkey-stamped, so it runs in the dashboard today).Fund it with USDC on Solana via:

Direct transfer from your existing wallet (Phantom, Solflare, etc.)
On-ramp from fiat via POST /v1/payout/onramp/deposit-accounts (Payout Kit)
A test airdrop (sandbox only)

6. Provision your first agent

Go to the dashboard → Agents → New agent. Provisioning is a 3-round passkey flow (the dashboard runs it end-to-end):

The dashboard prepares an unsigned user-create activity, you stamp it with your passkey
The dashboard submits the stamped activity, prepares a second activity for the agent’s policies, you stamp again
The dashboard submits the policies and shows you the agentSecret

The agentSecret is shown once. Copy it directly into your agent’s secret store. There is no recovery — if lost, rotate via POST /v1/agents/{id}/rotate.

Each agent gets:

A unique agentId (UUID)
Its own Solana USDC wallet (separate from your operator wallet)
An HMAC secret for SDK runtime auth

7. Configure the agent's budget

From the dashboard’s agent settings, define the spend limits (the dashboard runs a passkey-stamped POST /v1/agents/{id}/budget under the hood):

{
  "infrastructure": { "monthlyUSD": 50 },
  "tokens":         { "monthlyUSD": 200 },
  "payments":       {
    "monthlyUSDC": 1000,
    "perTxUSDC": 100,
    "approvalThresholdUSDC": 50
  }
}

Three layers enforced independently and atomically server-side:

Layer	What it caps	Failure mode
infra	API calls (cheap, frequent)	Fail-open on payments-only check
tokens	LLM token spend (Anthropic / OpenAI / Google)	Fail-open on payments-only check
payments	On-chain USDC transfers and x402 payments	Always blocks; never bypassable

Transactions above approvalThresholdUSDC require a CFO/operator to stamp approval with their passkey (delivered via the dashboard’s Approvals queue).

8. Fund the agent wallet

From the dashboard’s agent detail view, move USDC from your operator wallet to the agent wallet. The dashboard runs a 2-round passkey flow under the hood: it prepares the transfer activity, you stamp with your passkey, it broadcasts to Solana.Once funded, the agent can spend up to its payments budget.

9. Install the SDK

In the project where your agent runs:

pnpm add @relayerfi/agent-sdk

Requirements:

Node.js ≥ 22.13.0 — fetch, AbortSignal.timeout, node:crypto HMAC
ESM only — no CJS shim
TypeScript ≥ 5.0 if you want type definitions

Mastra integration (if you build agents with Mastra):

pnpm add @mastra/core
# The SDK exposes hooks via the @relayerfi/agent-sdk/mastra entry point.
# @mastra/core is an optional peer dep — installed only if you import the hooks.

10. Configure environment variables

Three env vars are required:

.env

RELAYER_AGENT_ID=agt_<from step 6>
RELAYER_AGENT_SECRET=<from step 6 — shown once>
RELAYER_API_URL=https://api.relayer.fi
# or for sandbox testing:
# RELAYER_API_URL=https://testnet.relayer.fi

Drop them in .env, your platform’s secret store, or your runtime config. Never log RELAYER_AGENT_SECRET — it’s the only thing that can sign API calls as this agent.

11. Initialize the SDK

Minimal init in your agent runtime:

src/sdk.ts

import { RelayerSDK } from "@relayerfi/agent-sdk";

export const sdk = new RelayerSDK({
  agentId: process.env.RELAYER_AGENT_ID!,
  secret: process.env.RELAYER_AGENT_SECRET!,
  apiUrl: process.env.RELAYER_API_URL!,
});

That’s it. The constructor:

Validates the 3 required fields
Starts the kill-switch poller (every 30s)
Starts the event batcher (flushes every 10s or on 50 events)
Registers SIGTERM / beforeExit handlers for graceful shutdown

See the SDK Reference for the full constructor config (retries, timeouts, custom intervals).

12. Make your agent spend money

The simplest paid action is calling any x402-protected HTTP endpoint:

import { sdk } from "./sdk";
import { x402fetch } from "@relayerfi/agent-sdk";

const response = await x402fetch(sdk, "https://paid-api.example.com/v1/run", {
  method: "POST",
  body: JSON.stringify({ input: "What's the current ETH price?" }),
});
const result = await response.json();

x402fetch is the one-liner that ties everything together: payment-budget check, HMAC auth, x402 detection, payment, and retry — all behind a normal fetch API.If you’re building with Mastra:

src/agent.ts

import { Agent } from "@mastra/core/agent";
import { sdk } from "./sdk";
import { relayerMastraHook } from "@relayerfi/agent-sdk/mastra";

const agent = new Agent({ /* your config */ });
const hook = relayerMastraHook(sdk);

await agent.generate("Generate a financial report", {
  onStepFinish: hook.onStepFinish,
});
// Token usage automatically tracked and emitted as llm_call events.

What you’ve built

By the end of step 12, you have:

A workspace in the Relayer dashboard with at least one passkey
An API key to call /v1/* from your backend
An operator wallet with USDC, owned by your workspace passkey
An agent with its own wallet, HMAC secret, and 3-layer budget caps
A deployed agent runtime that uses the SDK to pay for resources, with budget enforcement that cannot be bypassed — not even by a misbehaving LLM in your agent code

Where to go next

SDK Reference

Exhaustive reference for every class, method, event type, and error in @relayerfi/agent-sdk.

Agent Kit Flow Guide

The same flow as above but focused on the API endpoints — useful when you’re not using the dashboard.

Examples

Reference implementations: BI Agent (daily reports), OTC Agent (operator workflow), Outbound Agent (B2B sales).

Agent Kit

Documentation Index

​What you’ve built

​Where to go next

SDK Reference

Agent Kit Flow Guide

Examples

What you’ve built

Where to go next