pfp

$Tolkien — Documentation

Architecture, API, deployment, and operations.

← Back to App

Overview

The dashboard shows live stats and recent on-chain actions. The backend monitors market cap and, on every +$50k increment, executes: Collect creator rewards → Buy back 25% of claimed SOL → (Burn step next).

Environment

WALLET_ADDRESS=YourPublicKeyBase58
WALLET_PRIVATE_KEY=YourPrivateKeyBase58   # keep secret (backend env only)
SOLANA_RPC_URL=https://api.mainnet-beta.solana.com
HELIUS_API_KEY=YourHeliusKey
TOKEN_MINT=MintAddressOfYourToken
PRIORITY_FEE=0.000001
FRONTEND_ORIGIN=https://YOUR-VERCEL-APP.vercel.app

Note: Do not expose WALLET_PRIVATE_KEY in the frontend. Backend only.

API Reference

GET /health

{"ok": true}

GET /dashboard

Returns current metrics + recent transactions (for the horizontal cards).

{
  "price_usd": 34234.23,
  "volume_change_pct": 6212.5,
  "buybacks_usd": 10500.0,
  "burned_usd": 9500.0,
  "market_cap_usd": 325000.0,
  "next_goal_usd": 500000.0,
  "next_goal_progress_pct": 32.5,
  "supply_burned_pct": 9.1,
  "transactions": [
    {
      "signature": "BUYBACK_....",
      "kind": "buyback",  // claim | buyback | burn
      "amount_sol": 1.234,
      "status": "confirmed",
      "timestamp": "2025-09-25T18:00:00Z",
      "description": "Executed buy-back of 1.234 SOL"
    }
  ]
}

POST /actions/claim-and-buyback

Manual trigger (useful for testing). Automatically used by the 50k workflow.

POST /simulate/bump-mc

Dev-only helper to force MC thresholds while testing.

curl -X POST http://127.0.0.1:8000/simulate/bump-mc \
  -H "Content-Type: application/json" \
  -d '{"delta_usd":110000}'

Workflow

  1. Backend polls Helius to compute Market Cap for TOKEN_MINT.
  2. If MC crosses a new +$50k bucket → trigger:
    • Claim creator rewards.
    • Buy back with 25% of the claimed SOL.
    • Burn (next step in your pipeline) — dashboard already supports showing these txs.
  3. Each on-chain action is appended to transactions with a signature for Solscan.
  4. Frontend updates stat pills, progress bars, and the transaction cards automatically.

Frontend Integration

Set the backend URL in the page footer:

<script>
  window.API_BASE = 'https://your-backend.onrender.com';
</script>
<script src="/app.js"></script>

UI wiring:

Deployment

Operations & Troubleshooting