> For the complete documentation index, see [llms.txt](https://savefee.gitbook.io/savefee/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://savefee.gitbook.io/savefee/api-reference/overview.md).

# Overview

## Base URL

```
https://api.savefee.io
```

## Authentication

```
Authorization: Bearer sf_live_…
```

| Endpoints                   | Authentication                                                         |
| --------------------------- | ---------------------------------------------------------------------- |
| `/v1/balance`, `/v1/orders` | Required.                                                              |
| `/v1/broadcasts`            | Optional — it decides which account pays. See **POST /v1/broadcasts**. |
| `/v1/public/*`              | None.                                                                  |

Send the key with the `Bearer` scheme exactly as shown. A header using any other scheme is read as no key at all.

## Idempotency

`POST /v1/orders` requires an `Idempotency-Key` header, up to 128 characters. Use one unique value per logical order, and reuse the **same** value when retrying.

Broadcasts do not use the header — they are deduplicated by the transaction's own `txId`. Sending it anyway is harmless.

## Amounts

All monetary values are integers in `sun`. `1 TRX = 1,000,000 sun`.

## Identifiers

`orderId` and `broadcastId` are 24-character hexadecimal strings.

## Errors

All errors use the RFC 7807 envelope:

```json
{
  "type": "https://docs.savefee.io/errors/wallet-insufficient_balance",
  "title": "wallet.insufficient_balance",
  "status": 402,
  "detail": "Insufficient balance: required 1400000 sun",
  "instance": "/v1/orders",
  "code": "wallet.insufficient_balance",
  "requestId": "…"
}
```

Branch on `code`. Log `requestId`. See **Error codes**.

## Forward compatibility

Responses gain fields over time. Parse the fields you need and ignore the rest, and treat a status value you do not recognise as not yet finished.

## Request limits

| Limit                       | Value          |
| --------------------------- | -------------- |
| Request body                | 1 MiB          |
| `items[]` per order request | 100            |
| `Idempotency-Key` length    | 128 characters |

A body over the limit returns `413`.

## Rate limiting

Requests are rate limited and answer `429 rate_limited` when exceeded, with a `Retry-After` header. Wait that long, then retry with exponential backoff.