Getting Started

Quickstart

Make your first AI agent payment in under 5 minutes. This guide uses the TypeScript SDK, for Python, see the Python SDK reference.

Prerequisites

Node.js 18+ (or Bun / Deno)
A Fixer Protocol account at app.fixerprotocol.org
Your agent's API key (generated in the dashboard)
USDC in your agent wallet (see funding below)

1. Install the SDK

bash

npm install @fixerprotocol/sdk

Using Bun or pnpm? Same command, just swap the package manager prefix:

bash

bun add @fixerprotocol/sdk
# or
pnpm add @fixerprotocol/sdk

2. Get an API Key

Sign in at app.fixerprotocol.org and navigate to Settings → API Keys → Create Key. Give the key a name (e.g., my-agent-prod) and copy the value, it is only shown once.

Store the key in an environment variable, never hard-code it in source:

bash

# .env
FIXER_API_KEY=fxp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

⚠️

API keys are bearer tokens. Anyone with a key can submit payments on behalf of that agent. Treat them like passwords, use environment variables, secrets managers, or vaults. Never commit them to source control.

3. Make Your First Payment

Initialize the client and call fixer.pay(). The gateway automatically detects whether the target service uses x402 or MPP and handles all protocol negotiation for you.

typescript

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

const fixer = new FixerProtocol({
  agentId: "my-research-agent",
  apiKey: process.env.FIXER_API_KEY!,
});

// Make a payment — protocol detected automatically
const result = await fixer.pay({
  endpoint: "https://api.browserbase.com/v1/sessions",
  method: "POST",
  body: { url: "https://example.com" },
});

console.log(result.status);      // 200
console.log(result.txHash);      // "5xGh9...Kj3m" (Solana tx hash)
console.log(result.amountPaid);  // { usdc: 0.002 }
console.log(result.protocol);    // "x402" | "mpp"
console.log(result.data);        // actual API response from the service

ℹ️

Protocol detection is automatic. You never need to know or specify whether a service uses x402 or MPP. If a service supports both, Fixer Protocol selects x402 by default (lower overhead, fully on-chain). This is configurable via the dashboard.

4. Check Your Wallet Balance

Each agent gets a Solana wallet. Use rail.wallet to inspect it.

typescript

// Get full wallet info
const wallet = await fixer.wallet.get();
console.log(wallet.address);      // "7xKXtg...mQfJL" — Solana PDA
console.log(wallet.balance.usdc); // 42.50

// Or just the balance
const { usdc } = await fixer.wallet.balance();
console.log(`Balance: ${usdc} USDC`);

Funding your wallet

You can fund your agent wallet in three ways:

Direct USDC transfer: send USDC to the wallet address on Solana mainnet
Dashboard top-up: card payment at app.fixerprotocol.org (converts to USDC on-chain)
Programmatic fund: call fixer.wallet.fund({ usdc: 50 }) from your own Solana wallet

5. Set Spend Policies

Spend policies are enforced at the gateway before any payment is submitted, not after. A call that would breach the daily budget is rejected immediately. Set policies once and they apply to every subsequent call.

typescript

await fixer.policies.set({
  dailyBudget:    { usdc: 100 },       // max spend per calendar day
  perCallLimit:   { usdc: 1.00 },      // max single-payment amount
  allowedDomains: [                    // only allow payments to these hosts
    "api.dune.com",
    "api.browserbase.com",
    "fal.ai",
  ],
  blockedDomains: [],                  // explicit blocklist (optional)
  rateLimit:      { calls: 500, window: "1h" }, // max 500 calls per hour
});

console.log("Policies saved.");

💡

Start with conservative policies in development, a low dailyBudget and tight allowedDomains: then relax them as you test. Policy violations are logged on-chain, so you can audit rejected calls via the dashboard.

6. View Transaction History

typescript

// List recent transactions
const { transactions, total } = await fixer.transactions.list({
  limit: 20,
  protocol: "x402", // filter by protocol (optional)
});

for (const tx of transactions) {
  console.log(`${tx.txHash} — ${tx.amount.usdc} USDC — ${tx.protocol}`);
  console.log(`  Solana: ${tx.solanaTxLink}`);
}

// Fetch a single transaction
const tx = await fixer.transactions.get("5xGh9...Kj3m");
console.log(tx.status); // "confirmed" | "pending" | "failed"

Complete Example

A minimal TypeScript file that ties everything together:

typescript

import { FixerProtocol, PolicyViolationError, InsufficientFundsError } from "@fixerprotocol/sdk";

async function main() {
  const fixer = new FixerProtocol({
    agentId: "research-agent-v1",
    apiKey: process.env.FIXER_API_KEY!,
  });

  // Check balance before running
  const { usdc } = await fixer.wallet.balance();
  if (usdc < 1) {
    console.error("Low balance — fund your wallet before proceeding.");
    process.exit(1);
  }

  // Set guard-rails for this session
  await fixer.policies.set({
    dailyBudget:  { usdc: 50 },
    perCallLimit: { usdc: 0.50 },
  });

  // Make a payment
  try {
    const result = await fixer.pay({
      endpoint: "https://api.dune.com/api/v1/query/3326266/results",
      method: "GET",
    });

    console.log("Payment successful!");
    console.log("Solana tx:", result.txHash);
    console.log("Data:", result.data);
  } catch (err) {
    if (err instanceof PolicyViolationError) {
      console.error("Blocked by spend policy:", err.message);
    } else if (err instanceof InsufficientFundsError) {
      console.error("Wallet balance too low:", err.message);
    } else {
      throw err;
    }
  }
}

main();

Next Steps

🔧

SDK Reference

Every method, parameter, and type, documented with examples.

Browse SDK →

🕵️

ZK Privacy

Hide amounts, sender, and receiver using Groth16 zero-knowledge proofs.

Learn more →

📡

REST API

Call the gateway directly without an SDK, full endpoint reference.

View API →

🤝

Multi-Agent Payments

Pay sub-agents and trace the full payment chain on-chain.

Explore →