stars-cash-flow

Stars Cash Flow — reseller API skill

A universal skill for driving the Stars Cash Flow reseller API from any AI agent (Claude Code, Claude Desktop via MCP, a ChatGPT Custom GPT Action, or a self-hosted agent). It is a CPA exchange for real Telegram actions — subscribers, boosts and bot starts are fulfilled by real people who verify on Telegram's side, not bots.

Endpoint & auth

• Endpoint: POST https://api-stars.ros.media/api/v2 (form-encoded: application/x-www-form-urlencoded).
• Auth: every action except services needs an API key passed as the key field. Get a key from @StarsCashFlowbot → Reseller section. The key is tied to a USD balance.
• Rate limit: 60 requests / minute / key.
• Compatibility: drop-in for JustAnotherPanel — same actions and response shapes, only the URL and key differ.

Read the key from a secret/env var (STARS_CASH_FLOW_API_KEY). Never hardcode or print it.

Operations

All requests are POST with an action field.

action	fields	returns
services	—	array of services (id, name, rate USD/1000, min, max, …)
balance	key	{ balance, currency }
add	key, service, link, quantity	{ order } — spends balance
status	key, order or orders (csv, ≤100)	{ charge, start_count, status, remains, currency }
cancel	key, orders (csv)	{ canceled: [ids] } — refunds remainder

status values: In progress, Partial, Completed, Pending, Canceled.

Errors come back as { "error": "message" } with HTTP 200 — always check for an error field before trusting the payload.

🔴 Money rules (must follow)

add debits real USD from the reseller's balance. Before placing an order:

1. Always price first. Call services, find the service, and compute the cost: cost_usd = rate * quantity / 1000. Validate min ≤ quantity ≤ max.
2. Confirm the spend with the user. State the service, link, quantity and exact USD cost, and get an explicit "yes" before calling add. Never place an order the user did not approve in this turn.
3. One order per intent. The API is idempotent for ~120s on identical (service, link, quantity), but do not rely on it — do not retry add blindly on a timeout; check status/balance first.
4. cancel refunds only the unfulfilled remainder; already-delivered units are not refunded. Confirm before cancelling.