SDK Reference

npm install @fixerprotocol/sdk
# or: bun add @fixerprotocol/sdk  |  pnpm add @fixerprotocol/sdk

import { FixerProtocol } from "@fixerprotocol/sdk";

const fixer = new FixerProtocol({
  agentId: "my-agent",
  apiKey:  process.env.FIXER_API_KEY!,
  baseUrl: "https://api.fixerprotocol.org", // optional, this is the default
});

const result: PayResult = await fixer.pay(options: PayOptions);

const result = await fixer.pay({
  endpoint: "https://api.service.com/resource",
  method: "POST",
  body: { query: "..." },
  privacy: {
    mode: "full",                             // hide amount, sender, receiver
    disclosureKey: complianceOfficerPublicKey, // optional: auditor can decrypt
  },
});

console.log(result.txHash);          // Solana nullifier hash — no identity on-chain
console.log(result.privateNote);     // encrypted note for your records
console.log(result.disclosureProof); // openable only by disclosureKey holder

const wallet: WalletInfo = await fixer.wallet.get();
// {
//   agentId: "my-agent",
//   address: "7xKXtg2eH9sZ7pWbRqTJ3mQfJL...",  // Solana PDA
//   balance: { usdc: 42.50 }
// }

const balance: WalletBalance = await fixer.wallet.balance();
console.log(balance.usdc); // 42.50

const result: FundResult = await fixer.wallet.fund({
  usdc: 100,
  idempotencyKey: "top-up-2026-06-01", // optional
});

console.log(result.txHash);       // Solana tx hash of the funding transaction
console.log(result.amount.usdc);  // 100
console.log(result.balance.usdc); // updated balance after funding

const result: TransactionList = await fixer.transactions.list({
  limit:    50,
  offset:   0,
  protocol: "x402",             // filter by protocol (optional)
  from:     "2026-05-01",       // ISO 8601 date range (optional)
  to:       "2026-05-31",
});

const tx: Transaction = await fixer.transactions.get("5xGh9...Kj3m");
console.log(tx.status);       // "confirmed"
console.log(tx.solanaTxLink); // "https://explorer.solana.com/tx/5xGh9..."

const policy: SpendPolicy = await fixer.policies.get();
console.log(policy.dailyBudget?.usdc); // 100

const saved: SpendPolicy = await fixer.policies.set({
  dailyBudget:    { usdc: 100 },
  perCallLimit:   { usdc: 1.00 },
  allowedDomains: ["api.dune.com", "api.browserbase.com"],
  blockedDomains: ["badactor.com"],
  rateLimit:      { calls: 500, window: "1h" },
});

import {
  FixerProtocol,
  FixerError,
  AuthenticationError,
  InsufficientFundsError,
  PolicyViolationError,
  RateLimitError,
  APIError,
} from "@fixerprotocol/sdk";

try {
  const result = await fixer.pay({ endpoint: "https://api.service.com/" });
} catch (err) {
  if (err instanceof AuthenticationError) {
    // Invalid API key — check FIXER_API_KEY env var
    console.error("Auth failed:", err.message);
  } else if (err instanceof InsufficientFundsError) {
    // Wallet balance too low
    await topUpWallet();
  } else if (err instanceof PolicyViolationError) {
    // Blocked by a spend policy — log and skip
    console.warn("Policy blocked:", err.message);
  } else if (err instanceof RateLimitError) {
    // Too many calls — back off and retry
    await sleep(60_000);
  } else if (err instanceof APIError) {
    // Gateway returned an unexpected HTTP error
    console.error(`API error ${err.statusCode}:`, err.message);
  } else if (err instanceof FixerError) {
    // Any other Fixer-specific error
    console.error(`${err.code}:`, err.message);
  } else {
    // Network error, JSON parse error, etc.
    throw err;
  }
}

import type {
  FixerConfig,
  PayOptions,
  PayResult,
  PrivacyOptions,
  WalletInfo,
  WalletBalance,
  FundOptions,
  FundResult,
  Transaction,
  TransactionList,
  ListTransactionsOptions,
  SpendPolicy,
} from "@fixerprotocol/sdk";

pip install fixerprotocol

import os
import asyncio
from fixerprotocol import FixerProtocol

async def main():
    fixer = FixerProtocol(
        agent_id="my-research-agent",
        api_key=os.environ["FIXER_API_KEY"],
    )

    # Make a payment
    result = await fixer.pay(
        endpoint="https://api.fal.ai/v1/inference",
        method="POST",
        body={"model": "flux-pro", "prompt": "A futuristic city skyline"},
    )

    print(f"Status:     {result.status}")
    print(f"Tx hash:    {result.tx_hash}")
    print(f"Amount:     {result.amount_paid['usdc']} USDC")
    print(f"Protocol:   {result.protocol}")

    # Wallet balance
    balance = await fixer.wallet.balance()
    print(f"Balance:    {balance['usdc']} USDC")

    # Spend policies
    await fixer.policies.set(
        daily_budget={"usdc": 50},
        per_call_limit={"usdc": 0.50},
        allowed_domains=["api.fal.ai", "api.dune.com"],
    )

    # Transaction history
    result = await fixer.transactions.list(limit=10)
    for tx in result["transactions"]:
        print(f"  {tx['tx_hash']} — {tx['amount']['usdc']} USDC")

asyncio.run(main())

from fixerprotocol import (
    FixerProtocol,
    AuthenticationError,
    InsufficientFundsError,
    PolicyViolationError,
    RateLimitError,
    APIError,
)

try:
    result = await fixer.pay(endpoint="https://api.service.com/")
except AuthenticationError:
    print("Invalid API key")
except InsufficientFundsError:
    print("Wallet balance too low")
except PolicyViolationError as e:
    print(f"Blocked by policy: {e}")
except RateLimitError:
    print("Rate limit hit — back off and retry")
except APIError as e:
    print(f"API error {e.status_code}: {e}")