> 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/integration-guide/quickstart.md).

# Quickstart

This page assumes you already have an API key and a funded balance. If not, start with **Onboarding**.

## 1. Authenticate

Every request carries your API key as a bearer token. There is nothing else to set up: no signing, no session, no handshake.

```
Authorization: Bearer sf_live_…
```

{% hint style="warning" %}
Your API key is a bearer credential: anyone holding it can spend your balance. Keep it server-side. Never ship it in a browser, a mobile app, or a public repository.
{% endhint %}

## 2. Check your balance

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

```json
{
  "availableSun": 50000000,
  "depositAddress": "T… your personal deposit address …"
}
```

`availableSun` is what you can spend right now. An order costs the unit price times the amount of energy you buy, so quote it from `GET /v1/public/pricing` rather than assuming a figure, and keep your balance comfortably above a single order.

## 3. Place an order

```bash
curl -X POST https://api.savefee.io/v1/orders \
  -H "Authorization: Bearer $SAVEFEE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "toAddress": "<the address that should receive the energy>",
        "amount": 50000,
        "resource": "ENERGY",
        "durationSec": 3600
      }
    ]
  }'
```

A success looks like this:

```json
{
  "orders": [
    {
      "orderId": "65f1a2b3c4d5e6f708192a3b",
      "status": "pending",
      "receiver": "T…",
      "resource": "ENERGY",
      "resourceAmount": 50000,
      "remainAmount": 50000,
      "isMatching": true,
      "durationSec": 3600,
      "totalCostSun": 1400000,
      "createdAt": "2026-08-07T03:47:44.439Z"
    }
  ]
}
```

The status code is `201`. Your balance has already been debited by `totalCostSun`. The figures above are illustrative — the real `totalCostSun` reflects the live price at the moment the order was placed.

{% hint style="danger" %}
**Store `orderId` now.** Use `GET /v1/orders/{orderId}` to read an order detail and new status.
{% endhint %}

## 4. Wait for the energy to land

The order is not delivered yet — `status` is `pending`. In practice it reaches `fulfilled` in well under a minute, passing through `matching` and `executing` on the way.

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

```json
{
  "order": {
    "orderId": "65f1a2b3c4d5e6f708192a3b",
    "status": "fulfilled",
    "remainAmount": 0,
    "isMatching": false
  }
}
```

When `status` is `fulfilled` and `remainAmount` is `0`, the energy has been delegated. Keep polling on any other status.

## What to read next

* **Place an order** — pricing, batches, and how to retry safely.
* **Track an order** — every status value and what it means.
* **Webhooks** — be told when the energy lands instead of polling.