Prune — API Reference

Overview

The Prune public API exposes a single read-only endpoint that returns real-time bot stats for any user. It is designed to be called from external websites, dashboards, or browser widgets without exposing any sensitive credentials.

Property	Value
Base URL	`https://your-prune-domain`
Protocol	HTTPS (HTTP in local dev)
Format	JSON
Auth	`X-API-Key` header
Rate limit	None (be reasonable)

No sensitive data is returned. Keypairs, wallet secrets, Telegram tokens, and encrypted fields are never included in any public API response.

Authentication

Every request to the public API requires a valid API key in the X-API-Key header. Keys are generated on your Profile page under the API Keys section. You can have up to 3 active keys at once.

⚠ Keys are shown only once when created. Save them immediately. If you lose a key, delete it and generate a new one.

Key format: bb_ followed by 64 hex characters (67 chars total).

HTTP Request Header

X-API-Key: bb_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2

If the key is missing or invalid, the API returns:

401 Unauthorized

"detail": "Invalid API key"

Endpoint

GET /api/public/bots

Returns the authenticated user's profile and all their bots with live stats. Stats are read directly from the database and reflect the most recent values written by the running bot.

Request Headers

Header	Required	Description
`X-API-Key`	required	Your API key starting with `bb_`

Response Fields

user object Owner profile (public fields only)

display_name string Display name, or username if not set

username string Unique username (immutable)

bots array List of bots belonging to this user

name string Bot display name

token_symbol string Token ticker, e.g. PEPE

token_name string Full token name, e.g. Pepe Token

token_image_url string|null Token logo URL from DexScreener

is_running boolean true if the bot container is currently active

bot_mode string BUYBACK_AND_BURN, BUYBACK_ONLY, or ADD_LIQUIDITY

mode_config object Mode-specific allocation percentages

buyback_percent integer % of spendable SOL used per cycle — present for BUYBACK_AND_BURN and BUYBACK_ONLY

burn_percent integer % of bought tokens that are burned — present for BUYBACK_AND_BURN

liquidity_percent integer % of spendable SOL used for liquidity — present for ADD_LIQUIDITY

lp_action string "burn" or "hold" — what happens to received LP tokens — present for ADD_LIQUIDITY

lp_burn_percent integer|null % of LP tokens burned — present when lp_action is "burn"

stats object Persisted counters from the bot runtime

sol_spent_total string Total SOL spent (as decimal string, e.g. "1.234")

total_burned_raw string Total tokens burned in raw units (before decimals)

total_bought_raw string Total tokens bought in raw units (before decimals)

Example Response

JSON — 200 OK

{
  "user": {
    "display_name": "Alice",
    "username":     "alice"
  },
  "bots": [
    {
      "name":            "Pepe Buyback",
      "token_symbol":    "PEPE",
      "token_name":      "Pepe Token",
      "token_image_url": "https://dd.dexscreener.com/ds-data/tokens/solana/abc.png",
      "is_running":      true,
      "bot_mode":        "BUYBACK_AND_BURN",
      "mode_config": {
        "buyback_percent": 100,
        "burn_percent":    80
      },
      "stats": {
        "sol_spent_total":  "4.217832",
        "total_burned_raw": "84356000000",
        "total_bought_raw": "84356000000"
      }
    }
  ]
}

Code Examples

cURL

bash

curl https://your-prune-domain/api/public/bots \
  -H "X-API-Key: bb_YOUR_KEY_HERE"

JavaScript (fetch)

javascript

// Fetch and render bot stats
const res = await fetch("https://your-prune-domain/api/public/bots", {
  headers: {
    "X-API-Key": "bb_YOUR_KEY_HERE"
  }
});

const data = await res.json();
// data.user  → { display_name, username }
// data.bots  → array of bot objects with stats

for (const bot of data.bots) {
  console.log(
    bot.token_symbol,
    "SOL spent:", bot.stats.sol_spent_total,
    "Burned:",    bot.stats.total_burned_raw
  );
}

HTML Widget (copy-paste)

Drop this snippet into any webpage to embed a live burnbot stats card.

html

<!-- Prune Bot Stats Widget -->
<div id="prune-stats">Loading…</div>
<script>
(async () => {
  const res = await fetch("https://your-prune-domain/api/public/bots", {
    headers: { "X-API-Key": "bb_YOUR_KEY_HERE" }
  });
  if (!res.ok) return;
  const { bots } = await res.json();
  const el = document.getElementById("prune-stats");
  el.innerHTML = bots.map(b => `
    <div style="font-family:sans-serif;border:1px solid #2a1f3a;border-radius:8px;padding:1rem;margin:0.5rem 0;background:#100e16;color:#c4bdd4">
      <img src="${b.token_image_url || ''}" width="32" height="32" style="border-radius:50%;vertical-align:middle;margin-right:8px" />
      <strong style="color:#f0ecf8">${b.token_symbol}</strong>
      <span style="color:${b.is_running ? '#00e87a' : '#5a4f6e'};margin-left:8px">${b.is_running ? '● Running' : '○ Stopped'}</span>
      <div style="margin-top:0.5rem;font-size:0.85rem">
        SOL Spent: <strong style="color:#00c8ff">◎ ${(+b.stats.sol_spent_total).toFixed(3)}</strong>
        &nbsp;&nbsp;
        Burned: <strong style="color:#ff8c00">${Number(b.stats.total_burned_raw).toLocaleString()}</strong>
      </div>
    </div>
  `).join('');
})();
</script>

Python (requests)

python

import requests

res = requests.get(
    "https://your-prune-domain/api/public/bots",
    headers={"X-API-Key": "bb_YOUR_KEY_HERE"},
    timeout=10
)
data = res.json()

for bot in data["bots"]:
    print(
        bot["token_symbol"],
        "running:", bot["is_running"],
        "SOL spent:", bot["stats"]["sol_spent_total"]
    )

Error Codes

Status	Cause	detail value
`401`	Missing or invalid `X-API-Key`	`"Invalid API key"`
`422`	`X-API-Key` header not sent at all	Validation error object
`404`	User associated with key not found	`"User not found"`

All error responses follow the FastAPI convention:

JSON — Error shape

{ "detail": "Error message here" }