> 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/get-v1-broadcasts-broadcastid.md).

# GET /v1/broadcasts/{broadcastId}

## Request

```bash
curl https://api.savefee.io/v1/broadcasts/65f1a2b3c4d5e6f708192a3b \
  -H "Authorization: Bearer $SAVEFEE_API_KEY"
```

| Parameter     | In   | Description                                      |
| ------------- | ---- | ------------------------------------------------ |
| `broadcastId` | path | The 24-hex id returned by `POST /v1/broadcasts`. |

## Response `200`

The record is returned inside a `broadcast` wrapper:

```json
{
  "broadcast": {
    "broadcastId": "65f1a2b3c4d5e6f708192a3b",
    "kind": "usdt",
    "status": "confirmed",
    "txId": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "fromAddress": "T…",
    "toAddress": "T…",
    "amountAtomic": "1500000",
    "resource": "ENERGY",
    "resourceRequired": 64000,
    "energyRequired": 64000,
    "energyOrderId": "65f1a2b3c4d5e6f708192a3c",
    "totalCostSun": 1600000,
    "broadcastTxid": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "failureReason": null,
    "txExpirationMs": 1730000600000,
    "createdAt": "2026-08-07T03:47:44.439Z",
    "updatedAt": "2026-08-07T03:48:02.114Z"
  }
}
```

| Field                           | Description                                                                             |
| ------------------------------- | --------------------------------------------------------------------------------------- |
| `status`                        | Where the broadcast is in its lifecycle. See the table below.                           |
| `kind`                          | How SaveFee read the transaction: `usdt` for a USDT transfer, `tron` for anything else. |
| `txId`                          | The id of the transaction you signed.                                                   |
| `amountAtomic`                  | For a token transfer, the amount in the token's smallest unit. USDT has 6 decimals.     |
| `resource` / `resourceRequired` | The resource provisioned for this transaction, and how much of it.                      |
| `totalCostSun`                  | **What you were charged.** Read your accounting from here, not from a fixed fee.        |
| `broadcastTxid`                 | Present once the transaction has been pushed to the network.                            |
| `failureReason`                 | Why a `failed` or `expired` broadcast did not land.                                     |

Fields are added over time — read the ones you need and ignore the rest.

## Statuses

| `status`         | Finished | Meaning                                            | Balance         |
| ---------------- | -------- | -------------------------------------------------- | --------------- |
| `pending_energy` | no       | Accepted; the resource is being provisioned.       | already debited |
| `ready`          | no       | The resource is in place; queued to broadcast.     | already debited |
| `broadcasting`   | no       | Being pushed to the TRON network.                  | already debited |
| `confirming`     | no       | On the network, waiting for confirmation.          | already debited |
| `confirmed`      | **yes**  | On-chain and successful.                           | debit stands    |
| `failed`         | **yes**  | Not delivered.                                     | refunded        |
| `expired`        | **yes**  | Not confirmed before the transaction's expiration. | refunded        |

{% hint style="warning" %}
**Only `confirmed` means the transaction happened.** `confirming` already carries a `broadcastTxid`, but the network has not confirmed it yet — do not credit a customer on that. Treat any status you do not recognise as not yet finished and keep polling.
{% endhint %}

{% hint style="info" %}
`totalCostSun` was debited when the broadcast was accepted, not when it confirmed. On `failed` and `expired` it is returned by a separate refund entry.
{% endhint %}

## Errors

| Status | `code`                    | Cause                                                             |
| ------ | ------------------------- | ----------------------------------------------------------------- |
| `401`  | `api_key.invalid`         | Key missing or invalid.                                           |
| `403`  | `api_keys.ip_not_allowed` | The key has an IP allowlist and your source address is not on it. |
| `404`  | `not_found`               | Unknown id, or a broadcast not submitted by this key's account.   |

{% hint style="info" %}
For anything that moves customer money, treat the on-chain receipt for `txId` as the source of truth.
{% endhint %}