REST API

Authentication#

Public endpoints (GET /api/plans, GET /api/price, GET /api/auth) require no auth. All other endpoints require one of two methods:

Method 1: Wallet Signature (recommended)

Sign a message with any Solana wallet. No registration, no API keys, no database. Your wallet IS your identity.

1// 1. Get the message to sign
2const res = await fetch("https://buff.finance/api/auth")
3const { data } = await res.json()
4// data.message = "Buff API Authentication"
5
6// 2. Sign it with your wallet
7const message = new TextEncoder().encode(data.message)
8const signature = await wallet.signMessage(message)
9const sigBase64 = btoa(String.fromCharCode(...signature))
10
11// 3. Use on any protected endpoint
12fetch("https://buff.finance/api/roundup", {
13  method: "POST",
14  headers: {
15    "Content-Type": "application/json",
16    "x-wallet": wallet.publicKey.toBase58(),
17    "x-signature": sigBase64,
18  },
19  body: JSON.stringify({ txValueUsd: 27.63, plan: "tree" }),
20})

Method 2: Static API Key

For server-to-server integrations where wallet signing is not practical.

curl -X POST https://buff.finance/api/roundup \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{"txValueUsd": 27.63, "plan": "tree"}'

Method 3: Generate API Key Programmatically

For agents — sign the auth message with your keypair and get an API key. No browser needed.

Rate Limiting#

All API endpoints are rate-limited to 60 requests per minute per IP.

GET /api/auth#

Get the authentication message to sign.

GET /api/plans#

List all available plan tiers and defaults.

GET /api/price#

Get real-time token prices (cached 30s).

GET /api/portfolio/:address#

Read all token balances and USD values for any Solana wallet.

GET /api/accumulator/:address#

Check if a wallet has reached the investment threshold.

POST /api/roundup#

Calculate the round-up for a transaction value.

POST /api/wrap#

Get server-built transfer instructions with fees enforced. The treasury address is never exposed.

POST /api/swap/quote#

Get a Jupiter swap quote (SOL → target asset).

POST /api/swap/build#

Build unsigned Jupiter swap transactions. Server checks balance, validates threshold, and builds the swap.

POST /api/wallet/derive#

Derive a Buff wallet public key from a signature. Returns only the public key — never the private key.

POST /api/swap/execute#

Submit a pre-signed transaction to the Solana network. The transaction must already be signed.