> For the complete documentation index, see [llms.txt](https://tron-energy-doc.crypto-chief.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tron-energy-doc.crypto-chief.com/api-reference/balance.md).

# Credit Balance

## Credit Balance

What you have left to spend. Free, and it keeps answering at a zero or negative balance — checking your balance has to work exactly when you have none.

{% hint style="info" %}
Every field is documented below. The shape is the one the platform's own credits endpoint uses, so if you already parse that, the code you have works here unchanged.
{% endhint %}

#### **Credit Balance**

<mark style="color:blue;">`GET`</mark> `https://energy.crypto-chief.com/v1/balance`

**Headers**

| Name      | Value                                                     |
| --------- | --------------------------------------------------------- |
| Merchant  | Your project UUID                                         |
| Signature | [Signed request body](/getting-started/authentication.md) |

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "credits_balance": 125000000,
  "usd_balance": "12.50",
  "is_postpaid": true,
  "debt_limit_credits": 100000000,
  "timestamp": "2026-08-30T11:42:07Z"
}
```

{% endtab %}

{% tab title="503" %}

```json
{
  "ok": false,
  "error": "BALANCE_UNAVAILABLE",
  "msg": "could not read your balance just now"
}
```

{% endtab %}
{% endtabs %}

**Fields**

| Field                | Type    | Description                                                                                       |
| -------------------- | ------- | ------------------------------------------------------------------------------------------------- |
| `credits_balance`    | integer | The authoritative figure. 10,000,000 credits = $1. Negative on a postpaid project running a debt. |
| `usd_balance`        | string  | The same number as dollars, signed. A **string**, never a JSON number.                            |
| `is_postpaid`        | boolean | Whether this project may run a debt.                                                              |
| `debt_limit_credits` | integer | How far below zero you may go. `0` for a prepaid project.                                         |
| `timestamp`          | string  | RFC 3339, UTC.                                                                                    |

{% hint style="info" %}
Compare and store `credits_balance`; show `usd_balance`.
{% endhint %}

### Example

`sign()`, `canonical()`, `BASE`, `MERCHANT` and `API_KEY` are from [Authentication](/getting-started/authentication.md).

{% tabs %}
{% tab title="JavaScript" %}

```javascript
const res = await fetch(BASE + "/v1/balance", {
  headers: {
    Merchant: MERCHANT,
    Signature: GET_SIG,                  // md5(API_KEY) - see Authentication
  },
});
console.log(await res.json());
```

{% endtab %}

{% tab title="PHP" %}

```php
$ch = curl_init(BASE . "/v1/balance");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Merchant: ' . MERCHANT,
        'Signature: ' . $getSig,  // md5(API_KEY) - see Authentication
    ],
]);
print_r(json_decode(curl_exec($ch), true));
```

{% endtab %}

{% tab title="GO" %}

```go
req, _ := http.NewRequest("GET", base+"/v1/balance", nil)
req.Header.Set("Merchant", merchant)
req.Header.Set("Signature", getSig) // md5(apiKey) - see Authentication

res, err := http.DefaultClient.Do(req)
```

{% endtab %}

{% tab title="Python" %}

```python
res = requests.get(
    BASE + "/v1/balance",
    headers={
        "Merchant": MERCHANT,
        "Signature": GET_SIG,  # md5(API_KEY) - see Authentication
    },
)
print(res.json())
```

{% endtab %}

{% tab title="curl" %}

```bash
curl "$BASE/v1/balance" \
  -H "Merchant: $MERCHANT" \
  -H "Signature: $GET_SIG"
```

{% endtab %}
{% endtabs %}

### Your real headroom

For a postpaid project, what you can still spend is:

```
credits_balance + debt_limit_credits
```

This is what billing will actually allow, not a raw setting you have to interpret.

To find out what a specific purchase will cost before you order, ask for a [quote](/api-reference/quote.md) — they are free.

### Not a separate balance

There is no energy wallet. This is the same balance your PayIns, PayOuts and webhooks spend, and topping it up anywhere tops it up here.

### Rate limit

None. This endpoint is free and unthrottled, so it is safe to poll from a health check.

### Use it instead of probing

Never test whether you can afford an order by attempting one. This endpoint costs nothing and cannot move funds; an order can do both.