SDK Reference

// Core SDK
import { RelayerSDK, x402fetch, wrapAnthropic, wrapOpenAI, wrapGoogle } from "@relayerfi/agent-sdk";

// Errors
import {
  RelayerError,
  RelayerApiError,
  BudgetExhaustedError,
  KillSwitchActiveError,
  ApiUnreachableError,
  X402PaymentError,
  ApprovalTimeoutError,
  ApprovalRejectedError,
} from "@relayerfi/agent-sdk";

// Mastra integration (optional peer dep on @mastra/core)
import { relayerMastraHook } from "@relayerfi/agent-sdk/mastra";

new RelayerSDK(config: RelayerSDKConfig)

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!,
});

await sdk.checkBudget(); // throws BudgetExhaustedError if infra OR tokens exhausted

await sdk.checkPaymentBudget();
// throws KillSwitchActiveError if kill switch is active
// throws BudgetExhaustedError(["infra"|"tokens"|"payments"]) if any layer is empty

if (sdk.isKillSwitchActive) {
  // Skip payment operations; safe to continue with infra-only work.
}

sdk.emitEvent({
  type: "api_call",
  timestamp: new Date().toISOString(),
  agentId: sdk.agentId,
  data: { endpoint: "https://example.com/api", cost_usd: "0.001" },
});

const { wallet_id, addresses } = await sdk.createUserWallet({
  walletName: "Operations wallet",
  // optional — defaults to Solana ED25519
  accounts: [{ curve: "ed25519", pathFormat: "...", path: "m/44'/501'/0'/0'", addressFormat: "solana" }],
});

const headers = sdk.buildAuthHeaders("POST", "/v1/agents/self-bookkeeping", { foo: "bar" });
// {
//   "x-agent-id":          "agt_abc123",
//   "x-agent-auth":        "ad3f...",        // hex HMAC-SHA256
//   "x-request-timestamp": "1715772600",
//   "X-SDK-Version":       "@relayerfi/agent-sdk@1.0.0"
// }

const data = await sdk.http.post("/v1/agents/" + sdk.agentId + "/sign-transaction", {
  unsignedTx: base64Tx,
});

sdk.agentId;  // "agt_abc123"
sdk.apiUrl;   // "https://api.relayer.fi"

sdk.budget.get();      // BudgetStatus | null
// sdk.budget.refresh()  // not implemented yet — throws NotImplementedError

await sdk.shutdown();

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

const response = await x402fetch(sdk, "https://paid-api.example.com/v1/run", {
  method: "POST",
  body: JSON.stringify({ input: "..." }),
});
const data = await response.json();

import Anthropic from "@anthropic-ai/sdk";
import { wrapAnthropic } from "@relayerfi/agent-sdk";

const raw = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
const anthropic = wrapAnthropic(raw, sdk);

// Use exactly like the original — emits llm_call events automatically
const response = await anthropic.messages.create({
  model: "claude-opus-4-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello" }],
});

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

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

await agent.generate("Generate a financial summary", {
  onStepFinish: hook.onStepFinish,
});

import {
  RelayerError,         // base class
  RelayerApiError,      // any non-2xx response with statusCode + endpoint + body
  BudgetExhaustedError, // failedLayers: ("infra" | "tokens" | "payments")[]
  KillSwitchActiveError,// payment operations blocked because kill switch is active
  ApiUnreachableError,  // payment operations blocked because API is unreachable (fail-safe)
  X402PaymentError,     // x402 payment failed after retries
  ApprovalTimeoutError, // approval not resolved within `approvalTimeout`
  ApprovalRejectedError,// approval was actively rejected by a human approver
} from "@relayerfi/agent-sdk";

try {
  await x402fetch(sdk, url, init);
} catch (err) {
  if (err instanceof BudgetExhaustedError) {
    console.error(`Budget out on: ${err.failedLayers.join(", ")}`);
    return;
  }
  if (err instanceof KillSwitchActiveError) {
    console.warn("Agent is killed — stopping");
    process.exit(0);
  }
  if (err instanceof ApprovalRejectedError) {
    console.error(`Approval ${err.approvalId} was rejected`);
    return;
  }
  if (err instanceof ApprovalTimeoutError) {
    console.warn(`Approval ${err.approvalId} timed out — try smaller amount`);
    return;
  }
  if (err instanceof RelayerApiError) {
    console.error(`API ${err.statusCode} on ${err.endpoint}:`, err.body);
    return;
  }
  throw err;
}

sdk.emitEvent({
  type: "api_call",
  timestamp: new Date().toISOString(),
  agentId: sdk.agentId,
  data: { endpoint: "https://example.com/lookup", cost_usd: "0.0008" },
});