Backend Architecture¶

Purpose¶

The backend is a minimal wallet service called by LangGraph agents. It does NOT proxy frontend requests.

Endpoints¶

`POST /api/wallet/validate`¶

Validate a Cashu token without redeeming.

// Request
{ "token": "cashuA..." }

// Response
{ "valid": true, "amount": 10, "mint": "https://mint.example.com" }

`POST /api/wallet/receive`¶

Redeem a Cashu token to the backend wallet.

// Request
{ "token": "cashuA..." }

// Response
{ "success": true, "amount": 10 }

`GET /api/wallet/balance`¶

Get current wallet balance.

{ "balance": 1000, "mint": "https://mint.example.com" }

Pricing Endpoints¶

Token pricing in satoshis, calculated from USD pricing and live BTC price.

`GET /api/pricing/tokens`¶

Get satoshi-per-token pricing for a specific model. Called by LangGraph agents to determine costs.

// Request
GET /api/pricing/tokens?model=gpt-4o

// Response
{
  "model": "gpt-4o",
  "input_sats_per_token": 0.0025,
  "output_sats_per_token": 0.01,
  "btc_price_usd": 100000,
  "btc_price_source": "coinbase",
  "updated_at": "2026-01-02T12:00:00Z"
}

`GET /api/pricing/btc`¶

Get current BTC/USD price and source.

{
  "btc_price_usd": 100000,
  "source": "coinbase",
  "updated_at": "2026-01-02T12:00:00Z"
}

`GET /api/pricing/models`¶

List all known models and their USD pricing.

{
  "models": {
    "gpt-4o": {
      "input_usd_per_million": 2.5,
      "output_usd_per_million": 10.0
    },
    "grok-4-1-fast-non-reasoning": {
      "input_usd_per_million": 0.2,
      "output_usd_per_million": 0.5
    }
  }
}

`POST /api/pricing/refresh`¶

Manually trigger a BTC price refresh (for testing).

{
  "success": true,
  "btc_price_usd": 100000,
  "source": "coinbase",
  "updated_at": "2026-01-02T12:00:00Z"
}

Pricing Calculation¶

Satoshis per token is calculated as:

sats_per_token = (usd_per_million / 1,000,000) / btc_price_usd * 100,000,000

Example: GPT-4o input at $2.50/M tokens, BTC at $100k: - (2.50 / 1,000,000) / 100,000 * 100,000,000 = 0.0025 sats per token

Model Pricing Config¶

Model pricing is stored in backend/src/model_pricing.json and hot-reloaded on each request:

{
  "models": {
    "gpt-4o": {
      "input_usd_per_million": 2.50,
      "output_usd_per_million": 10.00
    }
  }
}

nutshell Integration¶

Uses the nutshell library (Cashu reference implementation):

from cashu.wallet.wallet import Wallet
from cashu.wallet.helpers import receive, deserialize_token

# Initialize wallet
wallet = await Wallet.with_db(url=MINT_URL, db="data/wallet")
await wallet.load_mint()

# Receive token
token = deserialize_token(token_str)
await receive(wallet, token)

Development Mode¶

Set DEV_MODE=true to: - Accept all tokens without validation - Skip actual mint communication - Simulate successful redemption

Configuration¶

Variable	Default	Description
`DEV_MODE`	`true`	Skip real validation
`MINT_URL`	minibits	Cashu mint URL
`WALLET_DB_PATH`	`data/wallet`	SQLite wallet path
`PORT`	`8000`	Server port
`BTC_PRICE_REFRESH_INTERVAL`	`300`	BTC price refresh interval in seconds (5 min)

ecash¶

Nutshell is a Chaumian Ecash wallet and mint for Bitcoin Lightning based on the Cashu protocol.

Cashu is a free and open-source Ecash protocol based on David Wagner's variant of Chaumian blinding called Blind Diffie-Hellman Key Exchange scheme written down here.