Wallet API: balance and transactions

Mirai Voice is prepaid. Every workspace has one INR wallet. Calls debit it when they end, text-to-speech requests debit it when they complete, AI flow drafts and recording transcriptions debit it when they finish, offline transcriptions debit it when a job completes, speech-to-text requests and sessions debit it for the audio they received, and top-ups credit it. If the wallet cannot cover a minute, POST /v2/calls returns 402 and no call is placed. For rates and how call time is counted — 10-second blocks, rounded up — see Billing & tiers.

Get balance

GET /v2/wallet

cURL
Python
Node.js

curl https://sandbox.voice.miraiminds.co/v2/wallet \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

import os, httpx

API = "https://sandbox.voice.miraiminds.co"
auth = {"Authorization": f"Bearer {os.environ['MIRAI_API_KEY']}"}

wallet = httpx.get(f"{API}/v2/wallet", headers=auth, timeout=30) \
              .raise_for_status().json()
print(wallet["balance_inr"])  # 500

const API = "https://sandbox.voice.miraiminds.co";
const auth = { Authorization: `Bearer ${process.env.MIRAI_API_KEY}` };

const wallet = await fetch(`${API}/v2/wallet`, { headers: auth }).then((r) => r.json());
console.log(wallet.balance_inr); // 500

200 OK

{
  "balance_inr": 500,
  "currency": "INR",
  "updated_at": "2026-07-26T09:12:44Z"
}

Field	Type	Description
`balance_inr`	number	Spendable balance. Never negative.
`currency`	string	Always `INR`.
`updated_at`	string	When the balance last changed.

Alert on this, don’t discover itPoll the balance on a schedule (hourly is plenty) and alert your own team below a threshold that covers a day of traffic. A 402 in the middle of a campaign is a much worse way to learn you are out of credit.

List transactions

GET /v2/wallet/transactions?limit=&cursor=

The ledger. One row per credit or debit, newest first.

cURL
Python
Node.js

curl "https://sandbox.voice.miraiminds.co/v2/wallet/transactions?limit=50" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

def all_transactions():
    cursor = None
    while True:
        params = {"limit": 100, **({"cursor": cursor} if cursor else {})}
        page = httpx.get(
            f"{API}/v2/wallet/transactions", headers=auth, params=params, timeout=30
        ).raise_for_status().json()
        yield from page["data"]
        if not page["has_more"]:
            return
        cursor = page["next_cursor"]

spent = sum(t["amount_inr"] for t in all_transactions() if t["type"] == "debit")

async function* allTransactions() {
  let cursor = null;
  for (;;) {
    const qs = new URLSearchParams({ limit: "100", ...(cursor ? { cursor } : {}) });
    const page = await fetch(`${API}/v2/wallet/transactions?${qs}`, { headers: auth })
      .then((r) => r.json());
    yield* page.data;
    if (!page.has_more) return;
    cursor = page.next_cursor;
  }
}

let spent = 0;
for await (const t of allTransactions()) if (t.type === "debit") spent += t.amount_inr;

200 OK

{
  "data": [
    {
      "id": "txn_01JZQ9D6P2R5S8T4V7W9X1Y3ZB",
      "object": "wallet_transaction",
      "type": "debit",
      "amount_inr": 5,
      "balance_after_inr": 495,
      "call_id": "call_01JZQ9B4M8N3P6R2S5T7V9W1YA",
      "kind": "call",
      "description": "call 96s @ t3",
      "billed_seconds": 100,
      "per_min_inr": 3,
      "billing_block_secs": 10,
      "pricing": {
        "voice_rate_paise": 300,
        "insights_rate_paise": 0,
        "telco_rate_paise": 0,
        "telco_block_seconds": 0,
        "rate_paise": 300,
        "block_seconds": 10,
        "insights_enabled": false
      },
      "created_at": "2026-07-26T09:16:39Z"
    },
    {
      "id": "txn_01JZQ8E2M4N6P8R1S3T5V7W9XA",
      "object": "wallet_transaction",
      "type": "credit",
      "amount_inr": 500,
      "balance_after_inr": 500,
      "call_id": null,
      "description": "pilot top-up",
      "created_at": "2026-07-26T08:40:11Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Field	Type	Description
`type`	`credit` \| `debit`	Direction.
`amount_inr`	number	Always positive; read `type` for direction.
`balance_after_inr`	number	Balance immediately after this row.
`call_id`	string \| null	Set on call debits, `null` on top-ups and adjustments.
`kind`	string	The transaction category: `call`, `tts`, `stt`, `flow_generation`, `transcription`, `number_rental`, `promotion` or `monthly_minimum`. Branch on this, never on `description`, and tolerate new categories.
`reference`	string	The id of the thing billed: the `tts_…` request id on a `tts` row; the `fgen_…` generation id, or the `ftr_…` transcription id, on a `flow_generation` row; the `trn_…` job id on a `transcription` row.
`quantity`	number	How much was billed: characters on a `tts` row, tokens (input plus output) on a `flow_generation` row, seconds of audio (rounded up) on a `transcription` row.
`description`	string	Human-readable. Do not parse it.
`promotional_inr`	number	Promotional credit granted on a `promotion` row, or the portion of a debit paid with promotional credit. Omitted when zero. Promotional credit does not count towards a monthly minimum.
`pricing`	object	The rates snapshotted when the call was admitted: voice AI, optional T1 insights, and any managed provider rate and billing block. Absent on historical rows.

The call amount combines voice and insights at the voice billing block, rounds that charge up to a paisa, then adds the separately rounded provider charge. BYO telco, WhatsApp and browser calls have no Mirai telco component.

kind, reference and quantity are additive. Rows written before they existed carry no kind — read a missing kind as call. Nothing else about the shape changed, so a reader that ignores all three keeps working.

Reconcile against call_id: every billable call produces exactly one debit row.

A text-to-speech row

Speech requests debit the same wallet, at ₹1.80 per 1,000 characters, and only when the audio was delivered in full:

{
  "id": "txn_01K4N7Q2R5S8T4V7W9X1Y3ZB6C",
  "object": "wallet_transaction",
  "type": "debit",
  "amount_inr": 0.12,
  "balance_after_inr": 494.88,
  "call_id": null,
  "kind": "tts",
  "reference": "tts_01K4N7Q0V8ZR3M6D9F2H5J7K1P",
  "quantity": 62,
  "description": "Text to speech · 62 characters · shruti",
  "created_at": "2026-09-09T09:16:39Z"
}

reference is the X-Request-Id the speech request returned, so a row reconciles against your request log the way a call row reconciles against call_id. On a WebSocket stream, each spoken sentence is its own row, and reference is the request_id from that sentence’s audio.done event. Fractions of a paisa carry over between sentences on a socket, so a sentence whose share rounds to nothing has a request-log row but no wallet row.

A flow generation row

Each AI flow draft is one debit, at the provider’s reported cost plus 20% (the chosen model’s token rates when the provider reports none):

{
  "id": "txn_01K8D5J7L9N1Q3S5U7W9Y1A3C5",
  "object": "wallet_transaction",
  "type": "debit",
  "amount_inr": 7.02,
  "balance_after_inr": 487.86,
  "call_id": null,
  "kind": "flow_generation",
  "reference": "fgen_01K8D5H2K4M6P8R0T2V4X6Z8B0",
  "quantity": 4532,
  "description": "Flow generation · claude-opus-5.5 · 1,512 in / 3,020 out tokens",
  "created_at": "2026-09-28T10:22:07Z"
}

reference is the id the generation returned, and quantity is its input and output tokens together. A generation that failed or was interrupted is charged the same way, and its description says so, for example Flow generation · gpt-6-sol · failed · 1,200 in / 2,400 out tokens.

A recording transcription row

Each recording transcription is one debit of the same kind, at the provider’s reported cost plus 20%:

{
  "id": "txn_01K8E2G6J8L0N2Q4S6U8W0Y2A4",
  "object": "wallet_transaction",
  "type": "debit",
  "amount_inr": 1.95,
  "balance_after_inr": 485.91,
  "call_id": null,
  "kind": "flow_generation",
  "reference": "ftr_01K8E2F4H6K8M0P2R4T6V8X0Z2",
  "quantity": 4634,
  "description": "Recording transcription · gemini-3.8-flash · 1m41s · 2,717 in / 1,917 out tokens",
  "created_at": "2026-09-29T11:04:52Z"
}

reference is the id the transcription returned, and quantity is its input and output tokens together; the description gives the recording’s length. A recording in which no conversation was heard is charged the same way, and its description says so, for example Recording transcription · gemini-3.8-flash · failed · 12s · 410 in / 96 out tokens. Tell a transcription from a draft by its reference prefix, ftr_ or fgen_.

An offline transcription row

Each completed offline transcription is one debit with kind: "transcription", at ₹18 per hour of audio. Degraded and failed jobs write no row.

{
  "id": "txn_01M3XRSP44KR3116AZ578NC2F1",
  "object": "wallet_transaction",
  "type": "debit",
  "amount_inr": 0.12,
  "balance_after_inr": 8762.06,
  "call_id": null,
  "kind": "transcription",
  "reference": "trn_01M3XRSFXW77RHEQ85979AJXAF",
  "quantity": 24,
  "description": "Transcription · 23s of audio · mira-transcribe-offline-1",
  "created_at": "2026-10-02T07:38:26Z"
}

reference is the job’s id, and quantity is the billed length in whole seconds, rounded up. These rows are separate from the recording transcriptions above, which turn calls into a flow and are billed as flow_generation.

Top up

Once your company has gone live, add credit yourself from the Billing page of the console, whenever you need it. Credit is spent at your workspace’s agreed rates. New T3 and T1 agreements fund their monthly minimum upfront into this wallet. Paid usage counts towards the minimum; any unused minimum is debited at the end of the billing month as a monthly_minimum transaction. The minimum is not an extra fee on top of usage. Top-ups above it remain available. Existing agreements retain their recorded funding terms. Before you go live, your Mirai contact credits the workspace. Promotional offers appear as promotion credits and are used before paid credit. They do not replace upfront monthly funding or satisfy the minimum. The Billing page shows your promotional balance, billing period and minimum-spend progress. A credit appears as a credit row and takes effect immediately. Your live balance is always GET /v2/wallet, and on the Developers page of the console. There is no top-up endpoint in the API.

Low balance alerts

Subscribe an endpoint to wallet.balance_low, wallet.depleted and wallet.balance_restored to hear when your balance drops below an alert level you choose (₹500 by default), when a call or campaign is refused for balance, and when you are back above the level. payment.succeeded and payment.failed report top-ups and failed debits. See webhook subscriptions.

`402` insufficient balance

Before dialling, we check the wallet can cover at least one minute at the call’s tier. If it cannot:

402 Payment Required

{
  "error": {
    "code": "insufficient_balance",
    "message": "wallet balance 0.40 INR is below the minimum for one minute at t3"
  }
}

The gate runs pre-dial. No phone rings, nothing is charged, no call object is created.
Retry after topping up, with the same Idempotency-Key — the failed request did not consume it.
Calls already in flight are not killed. A call that started with credit runs to its natural end, then debits. A wallet can therefore end a busy minute slightly lower than the pre-dial check implied.

Handle it explicitly — it is the one error that is a business condition rather than a bug:

Python
Node.js

r = httpx.post(f"{API}/v2/calls", headers=auth, json=payload, timeout=30)
if r.status_code == 402:
    pause_campaign()
    alert_ops(r.json()["error"]["message"])
else:
    r.raise_for_status()

const res = await fetch(`${API}/v2/calls`, { method: "POST", headers, body });
if (res.status === 402) {
  const { error } = await res.json();
  await pauseCampaign();
  await alertOps(error.message);
} else if (!res.ok) {
  throw new Error(await res.text());
}

Start here

Build

Prompting

Speech API

Text to speech

Speech to text

Language model

Money

Reference

Wallet API: balance and transactions

Get balance

List transactions

A text-to-speech row

A flow generation row

A recording transcription row

An offline transcription row

Top up

Low balance alerts

`402` insufficient balance

​Get balance

​List transactions

​A text-to-speech row

​A flow generation row

​A recording transcription row

​An offline transcription row

​Top up

​Low balance alerts

​402 insufficient balance

Get balance

List transactions

A text-to-speech row

A flow generation row

A recording transcription row

An offline transcription row

Top up

Low balance alerts

`402` insufficient balance