API pipeline: See your AI spend

Goal: see what the AI of your oracles and campaigns costs, by campaign and by oracle, and what is left on your balance.

Steps

1. Spend for a period.

GET /v0/my/funds/ai-usage?from=2026-10-01&to=2026-10-15
→ {"currency": "USDT", "from": "2026-10-01T00:00:00+00:00", "to": "2026-10-15T00:00:00+00:00",
   "charged_usd": 4.12, "requests": 830, "tokens": 9100000,
   "by_campaign": [{"campaign": "<campaign>", "charged_usd": 3.5, "requests": 700, "tokens": 8000000}],
   "by_oracle": [{"oracle": "<oracle>", "charged_usd": 0.62, "requests": 130, "tokens": 1100000}], …}

2. What is left. GET /v0/my/funds/check-balance → {"balance": "31.00", "currency": "USDT", "available": "30.60", …}. available is what your oracles and campaigns can still spend.

Price and charging

• AI usage is charged from your balance at the provider's price + 18%. charged_usd is that amount; the debits show in your transactions as AI_USAGE.
• When the balance runs out, your oracles and campaigns pause until you top up: API pipeline: Top up your balance with Telegram Stars, TON, USDT on TON or BTC

Rules

• from / to: RFC 3339 or YYYY-MM-DD (UTC); default from the start of the month to now. Bad values → 400.
• campaign: null = AI outside your campaigns; oracle: null = AI not tied to one of your oracles.
• An agenda or oracle token → 404: it has no spend of its own.

API surface

Index: API pipelines — index