Guide

Agent Integration

Run Buff in headless mode for AI agents, bots, and server-side scripts — no browser wallet required.

Why Headless Mode?

Browser wallets like Phantom work great for humans, but AI agents and automated systems need a different approach. Buff v1.0.0 uses API key authentication — no browser wallet or signMessage callback needed.

Method 1: API Key Authentication

The simplest approach for agents. Create a Buff instance with your API key and configure your plan.

agent-apikey.ts
typescript
1import { Buff } from "buff-protocol-sdk"
2
3const buff = new Buff({
4  apiKey: "your-api-key",
5  plan: "sprout",
6  investInto: "BTC",
7})
8
9// Derive a deterministic wallet from a signature
10const wallet = await buff.deriveWallet(agentSignature)
11console.log("Agent wallet:", wallet.pubkey)

Method 2: Register an Agent

Register your agent with a public key and agent ID. This helps track round-ups by agent in your analytics.

agent-register.ts
typescript
1import { Buff } from "buff-protocol-sdk"
2
3const buff = new Buff({
4  apiKey: "your-api-key",
5  plan: "sprout",
6  investInto: "BTC",
7})
8
9// Register agent for tracking and analytics
10await buff.registerAgent(agentPubkey, "claude-trading-bot")

Method 3: For Claude / GPT Agents

When running inside an AI agent framework, use the API key and register with an agent identifier for analytics.

agent-ai.ts
typescript
1import { Buff } from "buff-protocol-sdk"
2
3const buff = new Buff({
4  apiKey: process.env.BUFF_API_KEY,
5  plan: "sprout",
6  investInto: "BTC",
7  investThreshold: 5,
8})
9
10// Register the agent
11await buff.registerAgent(agentPubkey, "claude-trading-bot")
12
13// Calculate round-up for any spend
14const breakdown = await buff.calculateRoundUp(0.50)
15console.log("Round-up:", breakdown.roundUpUsd)

Funding the Agent Wallet

The agent wallet needs SOL to pay for round-ups and transaction fees. Derive a wallet using buff.deriveWallet() and transfer SOL to the returned address. On devnet, you can use the Solana faucet. On mainnet, transfer from an existing wallet or fund via an exchange.

  • –Minimum balance: ~0.01 SOL covers several hundred round-ups
  • –The agent wallet is a standard Solana keypair — fund it like any other wallet
  • –Use buff.deriveWallet(signature) to get a deterministic deposit address

Calculate Round-Ups for Non-Transaction Spends

Agents often pay for API calls, compute, or other services that aren't Solana transactions. Use calculateRoundUp() to compute the round-up amount, then use getWrapInstructions() to get the transfer instructions.

agent-roundup.ts
typescript
1// Calculate round-up for an API call cost
2const breakdown = await buff.calculateRoundUp(0.50)
3console.log("Round-up:", breakdown.roundUpUsd)
4
5// Get instructions to transfer the round-up amount
6const { instructions } = await buff.getWrapInstructions(
7  0.50, agentPubkey, buffWalletPubkey
8)
9
10// Build and execute swap when threshold is reached
11const { ready, transactions } = await buff.buildSwap(buffWalletPubkey)
12if (ready) {
13  for (const tx of transactions) {
14    const signed = signTransaction(tx) // sign with agent keypair
15    await buff.executeSwap(Buffer.from(signed).toString("base64"))
16  }
17}
Note
Agent wallets are fully non-custodial. All fee logic is handled server-side. The SDK is just an HTTP client to the buff.finance API.