API documentationshiba-bank.com · API
API · v1.1

Shiba Bank API

Credit Stars from your wallet in @shiba_bank_app to people's wallets straight from your own service: rewards for actions, prizes, payouts to moderators. The Stars never leave the bot: they move from wallet to wallet, like the +send command.

AI agents and services buy Stars and Telegram Premium for any @username, for USDT or GRAM on TON or with wallet Stars. Agents get an MCP server: orders, connecting.

Base URL
URL
https://shiba-bank.com/api/v1

How it works in plain words: the guide Telegram Stars API.

Contents
  1. Quick start
  2. Basics
  3. Keys and authentication
  4. Security
  5. Limits
  6. Idempotency and retries
  7. POST /transfers
  8. GET /transfers/{id}
  9. GET /transfers
  10. GET /balance
  11. GET /me
  12. GET /recipients/{telegram_id}
  13. GET /status
  14. Orders for AI agents
  15. POST /orders
  16. GET /orders/{id}
  17. GET /quote · GET /catalog
  18. POST /recipients/check
  19. MCP server
  20. Notification and comment
  21. Errors
  22. Code examples
  23. FAQ
  24. Changelog

Quick start

  1. Open @shiba_bank_app, send /api and press “🔑 Create key”. The key is shown once: store it in the SHIBA_API_KEY environment variable on your server.
  2. Top up your wallet in the bot: transfers are paid from your balance only.
  3. Check the key and the balance:
    curl
    curl https://shiba-bank.com/api/v1/balance -H "Authorization: Bearer $SHIBA_API_KEY"
  4. Send Stars:
    curl
    curl -X POST https://shiba-bank.com/api/v1/transfers \
      -H "Authorization: Bearer $SHIBA_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"telegram_id": 123456789, "amount": 5, "comment": "за модерацию никнейма", "notify": true, "idempotency_key": "moderation-8841"}'
    Answer:
    JSON
    {
      "success": true,
      "end_balance": 307,
      "replayed": false,
      "transfer": {
        "id": "tr_5f0c2a9e41b7d3c8a6e1f024",
        "status": "completed",
        "telegram_id": 123456789,
        "amount": 5,
        "comment": "за модерацию никнейма",
        "notify": true,
        "idempotency_key": "moderation-8841",
        "error": null,
        "end_balance": 307,
        "created_at": "2026-09-23T14:13:05.120931Z"
      }
    }

The bot messages the recipient with the amount, the sender and your comment unless notify is false.

Basics

  • HTTPS only. Requests and answers are UTF-8 JSON.
  • Every answer has success: true or false. With false comes an error object with a stable code (branch on it in your code), a human message and details, plus a request_id.
  • Every answer carries an X-Request-Id header: quote it when you contact support.
  • Amounts are whole Stars. Times are ISO 8601 in UTC, ending in Z.
  • Numbers may also be sent as a digit string ("5"); booleans only as true/false.
  • Unknown fields are refused (unknown_field), so a typo never becomes a silently ignored parameter.
  • The version is in the path, /api/v1. Within v1 fields are only added; nothing is removed or changes meaning.
HeaderWhenValue
AuthorizationalwaysBearer sbk_…
Content-TypePOSTapplication/json
Idempotency-KeyPOST /transfers, optional instead of the fieldsame as idempotency_key

Keys and authentication

Every request except /status carries the key in a header:

HTTP
Authorization: Bearer sbk_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

X-Api-Key: sbk_… works too. A key in the URL (?key=) is refused and should be treated as exposed.

  • A key is 256 random bits and starts with sbk_. The bot keeps only its SHA-256 fingerprint and shows the key once.
  • An account has one key. “♻️ New key” in /api switches the old one off at once; “🗑 Revoke” switches it off without a replacement. Limits and addresses are kept.
  • A key acts for its owner: their wallet pays, and the recipient sees them as the sender.

Security

What a key can do: read your balance, limits and its own transfers; check whether a person can receive Stars; send Stars from your wallet to people's wallets in the bot.

With orders turned on in /api the key can also: issue you USDT and GRAM invoices for Stars and Premium for any @username (you pay from your own TON wallet) and spend your wallet's Stars on such orders, within the limits. Orders are off by default.

What a key can never do: sell Stars, charge anybody else's wallet, change its own limits or addresses or turn orders on for itself, see other people's data. Settings change only inside the bot.

How to protect the key

  • Keep the key on your server only: in an environment variable or a secret store. Never in a repository, in client code, a mini app or a website: whatever reaches a browser or a phone can be read.
  • The API answers servers only: there are no CORS headers, so no web page can use your key from a browser.
  • Put your server's IP in /api → “🌐 Addresses”: the key stops working from anywhere else.
  • Set the limits to your real load: the daily limit is the most a leaked key can cost you.
  • Keep in the wallet what the next payouts need, not everything.
  • Suspect a leak? Press “♻️ New key” or “🗑 Revoke” at once. The old key stops working that very second.

What the server does

  • Every transfer goes the way +send goes: anti-fraud checks, frozen wallets and bans apply the same way.
  • One key's transfers run strictly one at a time and limits are counted atomically: parallel requests cannot slip past the daily limit.
  • An address sending many wrong keys is refused for a while before any key is checked.
  • The comment is cleaned of invisible and control characters and cannot contain links: the recipient reads it as your words, not the bot's.

Limits

WhatHow muchWhere to change
One transferdefault 500 ⭐, at most 100,000 ⭐/api → 📏
A day (UTC)default 2000 ⭐, at most 1,000,000 ⭐/api → 📅
Requests per account10 per second, bursts up to 30—
Transfers per account3 per second, bursts up to 10; one at a time—
Requests per IP10 per second, bursts up to 40 (beyond that, HTTP 429 from the web server)—
Request body4096 bytes—
Allowed addressesup to 10 IPs or networks/api → 🌐

The daily limit follows the UTC day (it resets at 00:00 UTC) and includes every completed or started transfer of the key. Current figures are in GET /me.

With 429 and 503 read the Retry-After header: that many seconds before a retry.

Idempotency and retries

Networks fail. If the answer to a transfer never arrived, you do not know whether the Stars moved. So every transfer carries your idempotency key, a stable name of the operation: moderation-8841, order-1234-reward, daily-2026-09-23-user-42. Repeat the request with the same key as often as you like: the Stars move once.

SituationWhat the API answers
A new keyMakes the transfer.
Same key, same fields, completedThe same answer, replayed: true, nothing charged again.
Same key, same fields, pendingFinishes that same transfer.
Same key, different fields409 idempotency_conflict.
Same key after a refusal (balance, limit, frozen)Tries again: a refusal moved nothing and did not take the key.

The rule is simple: derive the key from your data, never a fresh random one per attempt. A random key per attempt switches the double-payment protection off.

Safe to repeat: a network error, a timeout, HTTP 429, 500, 503. Do not repeat unchanged: other 4xx answers will not change by repetition.

StatusMeaning
completedThe Stars are with the recipient. Final.
pendingStarted, outcome not recorded yet (a dropped connection or a restart). Repeat the same request with the same key and it finishes.
refusedRefused, nothing moved. The code is in error.

POST /transfers — send Stars

Takes Stars from your wallet and credits them to the recipient's wallet in the bot.

FieldTypeRequiredDescription
telegram_idintegeryesThe recipient's Telegram id. They must have started @shiba_bank_app at least once.
amountintegeryesStars to send: a whole number from 1 to 100,000, and within the key's limit.
commentstringnoThe purpose of the payment, up to 255 characters. One line: line breaks and repeated spaces are joined. No links, domains, @mentions or hashtags.
notifybooleanno, trueWhether the bot messages the recipient about the credit.
idempotency_keystringyes*Your unique operation key, 1–64 characters A–Z a–z 0–9 _ - . :. May be sent as the Idempotency-Key header. *Not needed with dry_run.
dry_runbooleanno, falseCheck everything (key, recipient, limits, balance) and move nothing.

Request

curl
curl -X POST https://shiba-bank.com/api/v1/transfers \
  -H "Authorization: Bearer $SHIBA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"telegram_id": 123456789, "amount": 5, "comment": "за модерацию никнейма", "notify": true, "idempotency_key": "moderation-8841"}'

Success — 200

JSON
{
  "success": true,
  "end_balance": 307,
  "replayed": false,
  "transfer": {
    "id": "tr_5f0c2a9e41b7d3c8a6e1f024",
    "status": "completed",
    "telegram_id": 123456789,
    "amount": 5,
    "comment": "за модерацию никнейма",
    "notify": true,
    "idempotency_key": "moderation-8841",
    "error": null,
    "end_balance": 307,
    "created_at": "2026-09-23T14:13:05.120931Z"
  }
}
FieldDescription
successtrue: the Stars are credited.
end_balanceYour wallet balance right after this transfer.
replayedtrue when this repeats a completed transfer: nothing new was charged.
transfer.idOur transfer id, tr_….
transfer.statuscompleted, pending or refused.
transfer.errorThe refusal code of a refused one, otherwise null.

Checking without sending — dry_run

JSON
{
  "telegram_id": 123456789,
  "amount": 5,
  "dry_run": true
}
JSON
{
  "success": true,
  "dry_run": true,
  "end_balance": 307,
  "balance": 312
}

Error — 422

JSON
{
  "success": false,
  "error": {
    "code": "insufficient_balance",
    "message": "Not enough Stars in the wallet.",
    "balance": 3,
    "required": 5
  },
  "request_id": "req_9b1e04c27d5a6f33"
}

GET /transfers/{id} — one transfer

A transfer's state by our id (tr_…). Only your account's transfers are visible.

curl
curl https://shiba-bank.com/api/v1/transfers/tr_5f0c2a9e41b7d3c8a6e1f024 -H "Authorization: Bearer $SHIBA_API_KEY"
JSON
{
  "success": true,
  "transfer": {
    "id": "tr_5f0c2a9e41b7d3c8a6e1f024",
    "status": "completed",
    "telegram_id": 123456789,
    "amount": 5,
    "comment": "за модерацию никнейма",
    "notify": true,
    "idempotency_key": "moderation-8841",
    "error": null,
    "end_balance": 307,
    "created_at": "2026-09-23T14:13:05.120931Z"
  }
}

GET /transfers — transfer history

Your account's API transfers, newest first.

ParameterDescription
limit1–100, default 20.
cursornext_cursor of the previous answer: the next page.
statuspending | completed | refused
idempotency_keyFind a transfer by your own key: handy when an answer was lost.
telegram_idOnly transfers to this recipient.
curl
curl "https://shiba-bank.com/api/v1/transfers?limit=50&status=completed" -H "Authorization: Bearer $SHIBA_API_KEY"
JSON
{
  "success": true,
  "transfers": [
    {
      "id": "tr_5f0c2a9e41b7d3c8a6e1f024",
      "status": "completed",
      "telegram_id": 123456789,
      "amount": 5,
      "comment": "за модерацию никнейма",
      "notify": true,
      "idempotency_key": "moderation-8841",
      "error": null,
      "end_balance": 307,
      "created_at": "2026-09-23T14:13:05.120931Z"
    }
  ],
  "next_cursor": "tr_5f0c2a9e41b7d3c8a6e1f024"
}

next_cursor is null on the last page.

GET /balance — balance

How many Stars your wallet has available right now.

curl
curl https://shiba-bank.com/api/v1/balance -H "Authorization: Bearer $SHIBA_API_KEY"
JSON
{
  "success": true,
  "telegram_id": 555000111,
  "balance": 312
}

GET /me — key, limits, balance

Everything about the key in one request: whose it is, the limits, today's use, allowed addresses.

JSON
{
  "success": true,
  "telegram_id": 555000111,
  "username": "my_service_owner",
  "balance": 312,
  "key": {
    "prefix": "sbk_Q2x9aZ1p…",
    "created_at": "2026-09-23T10:00:00Z",
    "last_used_at": "2026-09-23T14:12:44Z"
  },
  "limits": {
    "per_transfer": 500,
    "daily": 2000,
    "used_today": 120,
    "remaining_today": 1880,
    "resets_at": "2026-09-24T00:00:00Z",
    "allowed_ips": [
      "203.0.113.7"
    ]
  },
  "api_version": "1.1"
}

GET /recipients/{telegram_id} — can they receive

A check before promising a reward: can_receive is true when the person has started @shiba_bank_app and their wallet is available. The API reveals no name or other data.

JSON
{
  "success": true,
  "telegram_id": 123456789,
  "can_receive": true
}

If false, ask the person to open @shiba_bank_app and press Start: Stars are never sent to an account the bot does not know, or they would be lost.

At most 200 checks per UTC day per account, then 429 rate_limited with retry_after until midnight. A dry_run and a transfer to someone this wallet has not paid before count as checks too; a new key does not reset the count, and an account can make at most 5 keys a day. Check the people you are about to pay, not lists.

GET /status — is the API up

No key needed. For monitoring.

JSON
{
  "success": true,
  "api_version": "1.1",
  "time": "2026-09-23T14:13:05Z",
  "docs": "/api/docs"
}

An OpenAPI 3.1 description for Postman, Swagger and code generators: /api/v1/openapi.json

Orders for AI agents

The key buys Stars and Telegram Premium for any @username. It is the bot's ordinary order: the same recipient check through Fragment, the same delivery and the same refunds, with a 3 % margin, below the bot's. Orders paid with wallet Stars carry no fee. Two ways to pay:

  • USDT or GRAM on TON (pay: usdt | gram). The API answers with an invoice: the project's address, the exact amount, a comment and a ready TON Connect transaction. Pay from your own wallet; the bot finds the payment on chain itself (usually within 10–40 seconds) and delivers.
  • Stars from the wallet in the bot (pay: wallet). The Stars come off your wallet and delivery starts at once: Stars one for one, Premium at its Stars price from /quote.

Turning it on

  1. @shiba_bank_app → /api → “🛒 Turn orders on”. While orders are off, /orders answers 403 orders_disabled.
  2. Invoice limits: “💵 Per order” and “📅 Invoices per day”, by default $50 per order and $200 per day, at most $1000 and $5,000. Wallet orders count against the key's Stars limits together with transfers.

The flow

  1. GET /quote — today's price in every way to pay.
  2. POST /recipients/check — whether the account can receive it.
  3. POST /orders — an invoice or a wallet order, with your idempotency_key.
  4. Pay payment: the exact amount and the exact comment.
  5. GET /orders/{id}?wait=25 — wait for delivered.

Order statuses

StatusMeaning
awaiting_paymentThe invoice waits for payment: payment holds the address, amount and comment.
processingA wallet order is accepted; the Stars or Premium are on their way.
payment_reviewA payment was found but does not match the invoice (say, less than the amount). A person reviews it.
paidThe payment is proven on chain; delivery starts.
deliveringDelivery through Fragment is under way.
deliveredDelivered. delivery holds the transaction hash and an explorer link. Final.
delivery_reviewA person checks the delivery: its proof is not found yet.
refundedCould not be delivered; refunded by the bot's rules, usually as Stars to the key owner's wallet. Final.
expiredThe invoice expired unpaid. Final.
canceledCanceled. Final.
failedThe order was not made: the code is in error. Nothing was taken.

Rules

  • One Stars invoice and one wallet withdrawal at a time per account: the next one after the previous is paid and delivered or has expired, otherwise 409 order_in_progress. Premium has no such rule.
  • At most ten unpaid invoices within ten minutes.
  • An invoice lives 30 minutes and its price is fixed when it is made. A late USDT payment is still accepted for a day; GRAM more than 30 minutes after the invoice ended is not counted by the bot, and such a payment is returned by hand.
  • A recipient check is a request to Fragment: once per 5 seconds after the first five. Orders: once per 3 seconds after the first five.
  • Receipts for orders reach the key owner in the bot's chat, as with an ordinary purchase.

POST /orders — order

FieldTypeRequiredDescription
productstringyesstars | premium
quantityintegeryesStars (between the minimum and maximum of /catalog) or Premium months: 3, 6, 12.
recipientstringyesThe recipient's public @username: @name, name or t.me/name.
paystringyesusdt or gram: an invoice for your TON wallet; wallet: Stars from your wallet in the bot.
idempotency_keystringyesYour name for this order; repeat it when you retry and there is one order. Or the Idempotency-Key header.
max_pricestringnoA price ceiling in what you pay with: USDT, GRAM or Stars. Above it: 409 price_above_max, nothing made.
payer_addressstringnoYour TON wallet's address: then a USDT invoice also comes with a ready TON Connect transaction.
dry_runbooleannoCheck everything (price, limits, recipient) and make nothing.

Request

curl
curl -X POST https://shiba-bank.com/api/v1/orders \
  -H "Authorization: Bearer $SHIBA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product": "stars", "quantity": 1000, "recipient": "@durov_fan", "pay": "usdt", "idempotency_key": "gift-2026-09-30-durov_fan", "max_price": "20"}'

Answer — 200

JSON
{
  "success": true,
  "replayed": false,
  "order": {
    "id": "ord_3c1f9e0a7b24d58e61c09a4f",
    "object": "order",
    "product": "stars",
    "quantity": 1000,
    "recipient": "durov_fan",
    "pay": "usdt",
    "status": "awaiting_payment",
    "idempotency_key": "gift-2026-09-30-durov_fan",
    "created_at": "2026-09-30T15:02:11Z",
    "price": {
      "currency": "USDT",
      "amount": "16.300000",
      "usd": "16.30"
    },
    "paid_at": null,
    "delivered_at": null,
    "payment": {
      "currency": "USDT",
      "network": "TON",
      "address": "UQ…project",
      "amount": "16.300000",
      "amount_units": "16300000",
      "decimals": 6,
      "comment": "a1B2c3D4e5F6g7H8",
      "expires_at": "2026-09-30T15:32:11Z",
      "link": "https://app.tonkeeper.com/transfer/UQ…?amount=16300000&text=a1B2c3D4e5F6g7H8&jetton=EQCx…",
      "ton_uri": "ton://transfer/UQ…?amount=16300000&text=a1B2c3D4e5F6g7H8&jetton=EQCx…",
      "jetton_master": "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs",
      "forward_ton_amount": "1",
      "checkout_url": "https://…/payments/direct?token=…",
      "important": "Send exactly this amount with exactly this comment: the comment is what ties the payment to the order."
    }
  }
}

How to pay

  • GRAM: send amount_units nanotons to address with the text comment comment. Or pass payment.tonconnect to TON Connect's sendTransaction: it is exactly that transfer.
  • USDT: a jetton transfer from your own USDT wallet: amount_units (6 decimals) to address, forward_ton_amount of at least 1 nanoton and the comment comment as the forward_payload. With payer_address in the request the ready transaction is in payment.tonconnect.
  • For people: link (Tonkeeper), ton_uri or the checkout_url page.

The comment is the only thing tying a payment to the order. Without it the bot cannot find the payment.

Python

Python
import os

import requests

API = "https://shiba-bank.com/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['SHIBA_API_KEY']}"}
FINAL = {"delivered", "refunded", "expired", "canceled", "failed"}


def buy_stars(username: str, stars: int, key: str) -> dict:
    """An invoice in USDT for `stars` Stars to @username; `key` names this purchase."""
    answer = requests.post(
        f"{API}/orders",
        headers=HEADERS,
        json={
            "product": "stars",
            "quantity": stars,
            "recipient": username,
            "pay": "usdt",
            "idempotency_key": key,  # the same key on every retry: one invoice
            "max_price": "20",  # refuse if it costs more than 20 USDT
        },
        timeout=30,
    ).json()
    if not answer["success"]:
        raise RuntimeError(answer["error"]["code"])
    order = answer["order"]
    pay = order["payment"]
    # Send exactly pay["amount"] USDT to pay["address"] with the comment
    # pay["comment"] from your own TON wallet -- or hand pay["tonconnect"]
    # to TON Connect (ask with "payer_address" to get it for USDT).
    while order["status"] not in FINAL:
        order = requests.get(
            f"{API}/orders/{order['id']}", params={"wait": 25}, headers=HEADERS, timeout=40
        ).json()["order"]
    return order

GET /orders/{id} — an order

ParameterDescription
wait0–25 seconds: answer as soon as the status changes. Better than frequent polling. One key holds at most 2 waits at a time; past that the order comes back at once with waited: false.
payer_addressFor an unpaid USDT invoice: build the TON Connect transaction for this wallet. At most 3 new wallets per account in 10 minutes; past that the invoice comes without tonconnect.
curl
curl "https://shiba-bank.com/api/v1/orders/ord_3c1f9e0a7b24d58e61c09a4f?wait=25" -H "Authorization: Bearer $SHIBA_API_KEY"

GET /orders?limit=20&before=ord_…: your orders, newest first, up to 50 at a time; next_before is the next page. The list carries no payment details: GET /orders/{id} does.

GET /quote · GET /catalog — prices and products

curl
curl "https://shiba-bank.com/api/v1/quote?product=stars&quantity=1000" -H "Authorization: Bearer $SHIBA_API_KEY"
JSON
{
  "success": true,
  "product": "stars",
  "quantity": 1000,
  "prices": {
    "usdt": {
      "currency": "USDT",
      "amount": "16.300000",
      "usd": "16.30"
    },
    "gram": {
      "currency": "GRAM",
      "amount": "5.114830000",
      "usd": "16.30"
    },
    "wallet": {
      "currency": "STARS",
      "amount": "1000"
    }
  },
  "valid_seconds": 20
}

Prices come from the formulas that price the bot's buttons, with the API's 3 % margin. /catalog names the products, the quantity bounds and the ways to pay available now.

POST /recipients/check — can the account receive it

JSON
{
  "recipient": "@durov_fan",
  "product": "stars",
  "quantity": 100
}
JSON
{
  "success": true,
  "recipient": "durov_fan",
  "product": "stars",
  "quantity": 100,
  "can_receive": false,
  "checked": true,
  "reason": "below_recipient_minimum",
  "minimum": 250,
  "message": "The account charges for messages: Telegram will not send it fewer Stars than that."
}

checked: false: Fragment did not answer; that is not a refusal, and the order checks the recipient again. Checks need orders turned on for the key: each one is a request to Fragment.

MCP server

Agents (Claude, Cursor, ChatGPT and any MCP client) take the API as a set of tools, with no code of your own. Streamable HTTP transport, JSON answers, the key in the same header.

Connection line · Claude Code
Shell
claude mcp add --transport http shiba-bank https://shiba-bank.com/api/mcp --header "Authorization: Bearer $SHIBA_API_KEY"
Cursor and other clients
JSON
{
  "mcpServers": {
    "shiba-bank": {
      "url": "https://shiba-bank.com/api/mcp",
      "headers": {"Authorization": "Bearer sbk_..."}
    }
  }
}

URL: https://shiba-bank.com/api/mcp

Tools

ToolWhat it does
get_accountThe key owner's Stars balance in the bot, the key's limits, whether orders are on and how much of today's limits (UTC) is used.
get_pricesWhat Stars or Premium cost now, for every way to pay: USDT, GRAM and wallet Stars.
check_recipientAsk Telegram (through Fragment) whether this account can receive this: not a channel or bot, no paid-message floor above the amount, no Premium already. Rationed: about one per 5 s.
create_orderBuy Stars or Premium for a Telegram @username. pay='usdt' or 'gram' returns an invoice to pay from your TON wallet (address, amount, comment, TON Connect transaction); pay='wallet' spends Stars from the key owner's bot wallet and delivers at once. dry_run=true checks and prices without ordering. max_price refuses the order above that price, in the unit you pay in.
get_orderAn order and its payment details. With wait_seconds (up to 25) it answers as soon as the status changes: awaiting_payment, paid, delivering, delivered, refunded, expired.
list_ordersThe key owner's API orders, newest first.
send_starsMove Stars from the key owner's bot wallet to another person's wallet in the bot, by Telegram id, with an optional comment. The person must have started the bot.

Without a key the server only introduces itself and lists its tools; calling them takes the key. Every tool is the same REST door with the same checks and limits.

Notification and comment

With notify: true the recipient gets a message from the bot in their own language:

⭐ You received 5 ⭐
From: @my_service_owner

💬 «for nickname moderation»
👛 Wallet · 312 Stars
  • The sender is the key owner: their @username, or their name and id without one.
  • Messages go through the bot's queue: usually within seconds, longer during mass payouts, but they arrive. The Stars are credited by the time the API answers; the message neither waits for them nor affects them.
  • If the person blocked the bot there is no message, but the Stars are in their wallet anyway.
  • notify: false is a silent credit: the Stars appear in the wallet without a message.

Comment rules

  • Up to 255 characters after cleaning; emoji are fine.
  • One line: line breaks and extra spaces become one space; invisible and control characters are removed.
  • Not allowed: links, domains (site.com), t.me/…, @mentions, hashtags: the answer is comment_not_allowed. This keeps the bot's message from becoming an ad or a phishing lure.
  • The comment is stored with the transfer and returned in transfer.comment.

Errors

JSON
{
  "success": false,
  "error": {
    "code": "insufficient_balance",
    "message": "Not enough Stars in the wallet.",
    "balance": 3,
    "required": 5
  },
  "request_id": "req_9b1e04c27d5a6f33"
}
CodeHTTPMeaning and what to do
invalid_json400The body is not a UTF-8 JSON object, or a field appears twice.
invalid_request400A field is missing, of the wrong type or out of range; field names it.
unknown_field400A field the API does not know (often a typo such as ammount).
invalid_comment400comment is not a string.
comment_too_long400The comment is longer than 255 characters.
comment_not_allowed400The comment contains a link, a domain, an @mention or a hashtag.
idempotency_key_required400A transfer without an idempotency key.
invalid_idempotency_key400The key has the wrong format, or the header and the body disagree.
key_in_url400The API key was sent in the URL. Treat it as exposed and issue a new one.
unauthorized401The key is missing, wrong or revoked.
key_blocked403API access of this account is blocked by the administration.
account_restricted403The key owner's account is restricted in the bot.
ip_not_allowed403The request's address is not allowed. ip is the address the server saw.
invalid_product400product is neither stars nor premium.
invalid_pay400pay is not usdt, gram or wallet.
invalid_quantity400The quantity is out of range: Stars from minimum to maximum, Premium 3, 6 or 12 months.
invalid_recipient400The recipient is not a public @username (4–32 Latin letters, digits, _).
invalid_max_price400max_price is not a positive number.
invalid_payer_address400payer_address is not a TON mainnet address.
orders_disabled403Orders are off for this key: turn them on in /api in the bot.
product_unavailable403This product is not on sale right now.
not_found404No such transfer or order (or it is not yours).
recipient_not_found404The recipient has never started the bot, or their wallet is unavailable.
idempotency_conflict409The key already belongs to a different transfer (recipient, amount, comment or notify differ).
price_above_max409The price is above your max_price; the current one is in price. Nothing was created.
price_changed409The price moved while ordering. Ask for the price again.
order_in_progress409The previous Stars invoice or wallet withdrawal is not finished (one at a time), or this very order is still being made. Repeat after Retry-After.
payload_too_large413The body is larger than 4096 bytes.
unsupported_media_type415No Content-Type: application/json header.
recipient_is_self422A transfer to yourself.
per_transfer_limit_exceeded422The amount is above the per-transfer limit (limit).
daily_limit_exceeded422The transfer would exceed the daily limit: limit, used_today, remaining.
insufficient_balance422Not enough Stars: balance and required. Nothing moved; the same key may be repeated after a top-up.
wallet_frozen422The sender's or the recipient's wallet is frozen or under review. Nothing moved.
transfer_refused422The wallet refused the transfer. Nothing moved.
account_too_new422The account cannot send Stars yet (hours_left).
recipient_not_user422This name belongs to a channel, group or bot, not to a person.
recipient_unknown422Telegram found no account with this name.
recipient_unavailable422Telegram takes no gifted Stars for this account right now.
recipient_has_premium422The account already has Telegram Premium.
below_recipient_minimum422The account charges for messages: Telegram sends it no fewer than minimum Stars.
order_limit_exceeded422The invoice is above the key's per-order limit (limit_usd).
order_refused422The order was refused; nothing was taken.
rate_limited429Too many requests. Wait Retry-After seconds.
too_many_failed_attempts429Too many wrong-key requests from your address. Check the key and wait.
too_many_unpaid_invoices429Ten unpaid invoices within ten minutes: pay them or let them expire.
internal_error500Our error. Contact support with the request_id.
api_disabled503The API is switched off for now.
busy503The transfer queue is busy. Repeat the same request after Retry-After.
outcome_unknown503The outcome is not known yet. Repeat the same request with the same key: it never pays twice.
inventory_unavailable503The bot cannot take this many Stars right now: order fewer, or later.
inventory_check_failed503The bot could not check its stock. Retry.
pay_unavailable503This way to pay is unavailable right now.
prices_unavailable503The bot cannot price this right now. Retry in a minute.
delivery_unavailable503Delivery is paused for now. Retry later.

Any 4xx answer means this request moved nothing. With 5xx the outcome may be unknown: repeat the same request with the same key.

Code examples

curl
curl -X POST https://shiba-bank.com/api/v1/transfers \
  -H "Authorization: Bearer $SHIBA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"telegram_id": 123456789, "amount": 5, "comment": "за модерацию никнейма", "notify": true, "idempotency_key": "moderation-8841"}'
Python
import os
import time

import requests

API = "https://shiba-bank.com/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['SHIBA_API_KEY']}"}


class ShibaApiError(Exception):
    def __init__(self, code: str, message: str, details: dict):
        super().__init__(f"{code}: {message}")
        self.code, self.details = code, details


def give_stars(telegram_id: int, amount: int, comment: str, key: str, notify: bool = True) -> int:
    """Credit Stars and return the balance left. Safe to call again with the same key."""
    payload = {
        "telegram_id": telegram_id,
        "amount": amount,
        "comment": comment,
        "notify": notify,
        "idempotency_key": key,
    }
    for attempt in range(6):
        try:
            response = requests.post(f"{API}/transfers", headers=HEADERS, json=payload, timeout=40)
        except requests.RequestException:
            time.sleep(2 ** attempt)  # the network failed: the same key is safe to repeat
            continue
        if response.status_code in (429, 503) or response.status_code >= 500:
            time.sleep(int(response.headers.get("Retry-After", 2 ** attempt)))
            continue
        data = response.json()
        if data["success"]:
            return data["end_balance"]
        error = data["error"]
        raise ShibaApiError(error["code"], error["message"], error)
    raise RuntimeError("the API did not answer; repeat later with the same key")


balance = give_stars(123456789, 5, "за модерацию никнейма", key="moderation-8841")
print("left:", balance)
JavaScript
// Node.js 18+ (global fetch)
const API = "https://shiba-bank.com/api/v1";

async function giveStars(telegramId, amount, comment, key, notify = true) {
  const body = JSON.stringify({
    telegram_id: telegramId, amount, comment, notify, idempotency_key: key,
  });
  for (let attempt = 0; attempt < 6; attempt++) {
    let res;
    try {
      res = await fetch(`${API}/transfers`, {
        method: "POST",
        headers: {
          "Authorization": `Bearer ${process.env.SHIBA_API_KEY}`,
          "Content-Type": "application/json",
        },
        body,
      });
    } catch (e) {
      await new Promise(r => setTimeout(r, 1000 * 2 ** attempt));
      continue;
    }
    if (res.status === 429 || res.status >= 500) {
      const wait = Number(res.headers.get("Retry-After") || 2 ** attempt);
      await new Promise(r => setTimeout(r, 1000 * wait));
      continue;
    }
    const data = await res.json();
    if (data.success) return data.end_balance;
    const err = new Error(`${data.error.code}: ${data.error.message}`);
    err.details = data.error;
    throw err;
  }
  throw new Error("the API did not answer; repeat later with the same key");
}

giveStars(123456789, 5, "за модерацию никнейма", "moderation-8841").then(console.log);
PHP
<?php
function give_stars(int $telegramId, int $amount, string $comment, string $key, bool $notify = true): int {
    $ch = curl_init("https://shiba-bank.com/api/v1/transfers");
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 40,
        CURLOPT_HTTPHEADER => [
            "Authorization: Bearer " . getenv("SHIBA_API_KEY"),
            "Content-Type: application/json",
        ],
        CURLOPT_POSTFIELDS => json_encode([
            "telegram_id" => $telegramId,
            "amount" => $amount,
            "comment" => $comment,
            "notify" => $notify,
            "idempotency_key" => $key,
        ], JSON_UNESCAPED_UNICODE),
    ]);
    $raw = curl_exec($ch);
    curl_close($ch);
    if ($raw === false) {
        throw new RuntimeException("network error: repeat with the same key");
    }
    $data = json_decode($raw, true);
    if (!$data["success"]) {
        throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]);
    }
    return $data["end_balance"];
}

Mass payout

There is no batch method: send transfers one by one, each with its own key (say payout-2026-09-23-<telegram_id>). If the script dies halfway, run it again from the start: completed transfers come back with replayed: true and are not charged twice.

Python
for user_id, stars in winners:
    give_stars(user_id, stars, "приз недели", key=f"weekly-2026-39-{user_id}")

FAQ

Where do the Stars for transfers come from?
Only from your wallet in @shiba_bank_app. Top it up in the bot: “👛 Wallet” → “Top up”.
What can the recipient do with the Stars?
Everything any wallet Stars allow: withdraw to their Telegram account, sell, give away in a chat, send as a cheque.
Can a transfer be undone?
No. A completed transfer is final, like +send. Use dry_run to check first.
How do I get a person's Telegram id?
Telegram sends it in every update to your bot: message.from.id. The API does not send by @username: usernames change, ids do not.
How much does the API cost?
Nothing. Transfers between wallets carry no fee.
I got 503 outcome_unknown: did the Stars move?
Repeat the same request with the same key: the final answer comes back, never a double charge. Or look at GET /transfers?idempotency_key=….
Need a webhook for incoming transfers, or to accept payment in Stars?
Tell the bot's support what exactly you need: that decides what the next versions add.

Changelog

1.1 — 30.09.2026. Orders of Stars and Telegram Premium for any @username for USDT, GRAM or wallet Stars; prices, catalog, recipient checks through Fragment, status long-polling (wait), ready TON Connect transactions, an MCP server for AI agents.

1.0 — 23.09.2026. Transfers, balance, limits, history, recipient check, OpenAPI.

QR code of the link to Telegram

Open in Telegram

Point your phone's camera at the code

Open in Telegram Desktop

The Shiba Bank window opens in Telegram.A chat with the bot @shiba_bank_app opens.Telegram will ask you to pick a group and give the bot admin rights.