# Introduction

Send or Receive SMS programmatically, pay with Lightning.

[sms4sats.com](https://sms4sats.com) lets you generate SMS activation code orders from anywhere, pay with Lightning Bitcoin, and receive the activation codes programmatically.

AI agents can use <https://api.sms4sats.com/skill.md> to use the service autonomously over the [L402 protocol](https://github.com/lightninglabs/L402) with no human intervention.

### Quick Start

1. Check available countries → [Get Countries](/api-reference/get-countries)
2. Check available services for a country → [Get Available Services](/api-reference/get-services)
3. Check pricing → [Get Price](/api-reference/get-price)
4. Create an order → [Create Receive Order](/api-reference/create-receive-order)
5. Poll for your activation code → [Get Order Status](/api-reference/get-order-status)

### API Base URL

```
https://api2.sms4sats.com
```

You can also hit this root endpoint to check for service availability.

### Contact

| Channel  | Link                                                                            |
| -------- | ------------------------------------------------------------------------------- |
| Telegram | [pseudozach](https://t.me/pseudozach) or [t.me/sms4sats](https://t.me/sms4sats) |
| Email    | <support@sms4sats.com>                                                          |
| Twitter  | [twitter.com/sms4sats](https://twitter.com/sms4sats)                            |
| Sales    | <sales@sms4sats.com> (volume discounts)                                         |

{% hint style="info" %}
Get in touch for volume discounts: <sales@sms4sats.com>.
{% endhint %}


# Overview

Everything you need to know before making your first API call.

sms4sats is a pay-per-use SMS service backed by Bitcoin Lightning Network. There are no accounts required — just generate an order, pay the Lightning invoice, and receive your SMS activation code.

### How It Works

1. **Create an order** with your desired country and service (e.g. USA + Google).
2. **Pay the Lightning invoice** returned by the API using any Lightning wallet.
3. **Poll the order status** endpoint until your activation code arrives.
4. **Cancel** anytime after 2 minutes if no code has arrived — your payment is automatically returned.

{% hint style="success" %}
sms4sats uses [hold invoices](https://bolt.fun/guide/invoices/hodl-invoice). Your funds are only settled when an activation code is successfully delivered. If no code arrives within 21 minutes, the invoice is automatically canceled and funds returned.
{% endhint %}

### Payment Options

| Method            | Details                                                                                |
| ----------------- | -------------------------------------------------------------------------------------- |
| Bitcoin Lightning | Native payment method. Instant, no fees, no account.                                   |
| USDT / LTC / ETH  | Swap to Lightning BTC via [FixedFloat](https://fixedfloat.com/ETH/BTCLN?ref=pmdxabka). |

### Prepaid Account (API Key)

For automated or high-volume usage, you can fund a prepaid account with an API Key to skip the per-order invoice payment step. See [Fund Account](/api-reference/fund-account) and [Get Balance](/api-reference/get-balance).

### L402 / AI Agents

AI agents can use <https://api.sms4sats.com/skill.md> to operate the service autonomously via the [L402 protocol](https://github.com/lightninglabs/L402) with no human intervention.


# Node Info

Connect directly to the sms4sats Lightning Node for reliable payment routing.

Feel free to open a direct channel to our Lightning node if you have trouble with routing, or reach out and we are happy to open balanced channels to high-volume partners.

{% embed url="<https://amboss.space/node/035b04e00521a8d50894e813c72576d2a03a09cd940be074b7f2e35e0a01d7d12d>" %}
sms4sats Lightning Node on Amboss
{% endembed %}

### Node Details

| Field    | Value                                                                                                                         |
| -------- | ----------------------------------------------------------------------------------------------------------------------------- |
| Pubkey   | `035b04e00521a8d50894e813c72576d2a03a09cd940be074b7f2e35e0a01d7d12d`                                                          |
| Explorer | [amboss.space/node/035b04e0...](https://amboss.space/node/035b04e00521a8d50894e813c72576d2a03a09cd940be074b7f2e35e0a01d7d12d) |

### Contact for Channel Partners

Telegram: [pseudozach](https://t.me/pseudozach) or [t.me/sms4sats](https://t.me/sms4sats)

Email: <support@sms4sats.com>


# Wallets & Payments

Lightning wallets and swap services to pay sms4sats invoices.

sms4sats invoices are standard Lightning Network invoices (BOLT11). Any Lightning-compatible wallet can be used to pay them.

### Lightning Wallets

{% embed url="<https://lightsats.com/guide/wallets>" %}
Lightsats Wallet Guide
{% endembed %}

{% embed url="<https://darth-coin.github.io/wallets/lightning-wallets-comparison-en.html>" %}
Lightning Wallet Comparison
{% endembed %}

### Swap Other Cryptocurrencies to Lightning BTC

If you hold USDT, LTC, ETH, or other assets, you can swap them to Bitcoin on Lightning Network to pay invoices:

{% embed url="<https://fixedfloat.com/ETH/BTCLN?ref=pmdxabka>" %}
FixedFloat — Swap to Lightning BTC
{% endembed %}

{% hint style="info" %}
Swaps typically complete in a few minutes. Make sure the output amount covers the invoice value before initiating a swap.
{% endhint %}


# Postman Collection

Run and explore the full sms4sats API in Postman.

You can run the complete sms4sats API in Postman to explore all endpoints, inspect parameters, and test responses interactively.

[![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/92744-f0d90622-bd11-46c2-88d9-8a28c4659c14?action=collection%2Ffork\&collection-url=entityId%3D92744-f0d90622-bd11-46c2-88d9-8a28c4659c14%26entityType%3Dcollection%26workspaceId%3D1b640623-2040-457e-a2b5-a901b273ff18)

Click the button above to fork the collection into your own Postman workspace. All endpoints are pre-configured with example request bodies and documented parameters.


# Overview

Complete reference for all sms4sats API endpoints.

All endpoints are served from the base URL:

```
https://api2.sms4sats.com
```

You can also GET the base URL to check for service availability.

### Authentication

Most endpoints require no authentication. For prepaid account operations (immediate deduction from balance), pass your API Key in the `X-API-Key` request header.

### Payment Model

sms4sats uses [hold invoices](https://bolt.fun/guide/invoices/hodl-invoice):

* Payment is **held** (not settled) when the invoice is paid.
* For **receive** orders — settled only when an activation code is delivered.
* For **send** orders — settled only when SMS status is `sent` or `delivered`.
* If no code arrives within **21 minutes**, the invoice is automatically **canceled** and funds returned.

### Endpoint Overview

| Method | Endpoint              | Description                           |
| ------ | --------------------- | ------------------------------------- |
| `GET`  | `/getCountries`       | List available countries              |
| `GET`  | `/getnumbersstatus`   | List available services for a country |
| `GET`  | `/getRentalCountries` | List countries with rental numbers    |
| `GET`  | `/price`              | Get price for a country/service       |
| `POST` | `/createorder`        | Create a receive SMS order            |
| `GET`  | `/orderstatus`        | Get order status and activation code  |
| `GET`  | `/cancelorder`        | Cancel a receive order                |
| `POST` | `/createsendorder`    | Create a send SMS order               |
| `POST` | `/fund`               | Fund a prepaid account                |
| `GET`  | `/balance`            | Get prepaid account balance           |
| `GET`  | `/history`            | Get prepaid account funding history   |


# Get Countries

Retrieve the list of all available countries and their country codes.

<mark style="color:blue;">`GET`</mark> `https://api2.sms4sats.com/getCountries`

Returns an array of available countries with their corresponding country codes. Use the `id` field as the `country` parameter in other endpoints.

{% hint style="info" %}
The API also accepts country names as strings (e.g. `country="germany"`) in most endpoints. Use this endpoint when you need to look up exact numeric country codes.
{% endhint %}

#### No Parameters Required

{% tabs %}
{% tab title="200: OK" %}
{% code overflow="wrap" %}

```javascript
[
    {
        "id": 0,
        "rus": "Россия",
        "eng": "Russia",
        "chn": "俄罗斯",
        "visible": 0,
        "retry": 1,
        "rent": 0,
        "multiService": 0
    },
    ...
]
```

{% endcode %}
{% endtab %}
{% endtabs %}

### Response Fields

| Field          | Type   | Description                            |
| -------------- | ------ | -------------------------------------- |
| `id`           | Number | Country code to use in API requests    |
| `eng`          | String | Country name in English                |
| `rus`          | String | Country name in Russian                |
| `chn`          | String | Country name in Chinese                |
| `visible`      | Number | Whether the country is shown in the UI |
| `retry`        | Number | Whether retry is available             |
| `rent`         | Number | Whether rental numbers are available   |
| `multiService` | Number | Whether multi-service is supported     |


# Get Available Services

Get available services (with number counts) for a specific country.

<mark style="color:blue;">`GET`</mark> `https://api2.sms4sats.com/getnumbersstatus`

Returns a list of services for which SMS activation numbers are currently available in the given country, along with the count of available numbers.

#### Query Parameters

| Name      | Type   | Required | Description                                                                           |
| --------- | ------ | -------- | ------------------------------------------------------------------------------------- |
| `country` | Number | Yes      | Country code (e.g. `187` for USA). See [Get Countries](/api-reference/get-countries). |

{% tabs %}
{% tab title="200: OK" %}
{% code overflow="wrap" %}

```javascript
[
    {
        "key": "vk",
        "text": "vk.com",
        "value": "vk",
        "count": "28",
        "image": {
            "avatar": true,
            "src": "/assets/saimages/vk0.png"
        }
    },
    ...
]
```

{% endcode %}
{% endtab %}
{% endtabs %}

### Response Fields

| Field   | Type   | Description                                                                        |
| ------- | ------ | ---------------------------------------------------------------------------------- |
| `key`   | String | Service identifier                                                                 |
| `text`  | String | Human-readable service name                                                        |
| `value` | String | Service code to use in [Create Receive Order](/api-reference/create-receive-order) |
| `count` | String | Number of currently available numbers                                              |

{% hint style="info" %}
Use the `value` field from this response as the `service` parameter when calling [Create Receive Order](/api-reference/create-receive-order).
{% endhint %}


# Get Rental Countries

Get a list of countries that have rental phone numbers available.

<mark style="color:blue;">`GET`</mark> `https://api2.sms4sats.com/getRentalCountries`

Returns a list of countries that have rental phone numbers available, along with pricing and rental duration.

#### Query Parameters

| Name      | Type   | Required | Description                                                                              |
| --------- | ------ | -------- | ---------------------------------------------------------------------------------------- |
| `service` | String | No       | Rental service code (e.g. `fb` for Facebook). Defaults to `full` for full rental access. |

{% tabs %}
{% tab title="200: OK" %}
{% code overflow="wrap" %}

```javascript
[
    {
        "cc": 6,
        "country": "Indonesia",
        "duration": "2",
        "price": 1368
    },
    {
        "cc": 16,
        "country": "England",
        "duration": "2",
        "price": 4815
    },
    ...
]
```

{% endcode %}
{% endtab %}
{% endtabs %}

### Response Fields

| Field      | Type   | Description                                                                        |
| ---------- | ------ | ---------------------------------------------------------------------------------- |
| `cc`       | Number | Country code to use in [Create Receive Order](/api-reference/create-receive-order) |
| `country`  | String | Country name                                                                       |
| `duration` | String | Rental duration in weeks                                                           |
| `price`    | Number | Price in satoshis                                                                  |

{% hint style="info" %}
To create a rental order, pass `isRental: true` in the [Create Receive Order](/api-reference/create-receive-order) request.
{% endhint %}


# Get Price

Check the price in satoshis for any country and service combination.

<mark style="color:blue;">`GET`</mark> `https://api2.sms4sats.com/price`

Returns pricing in satoshis for receive, send, and rental operations. Optionally pass a country and service to get the exact computed price for that combination.

#### Query Parameters

| Name      | Type             | Required | Description                                                     |
| --------- | ---------------- | -------- | --------------------------------------------------------------- |
| `country` | Number or String | No       | ISO country name or numeric country code (e.g. `"us"` or `187`) |
| `service` | String           | No       | Short or long service name (e.g. `"google"`, `"tg"`, `"ot"`)    |

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

```javascript
{
    "receive": "1500",
    "send": 3000,
    "rent": 15000,
    "s4s": "4000",
    "query": {
        "country": "us",
        "service": "google"
    },
    "computed": {
        "price": 1500,
        "country": 187,
        "description": "sms4sats payment US google"
    }
}
```

{% endtab %}
{% endtabs %}

### Response Fields

| Field                  | Type   | Description                                            |
| ---------------------- | ------ | ------------------------------------------------------ |
| `receive`              | String | Price to receive an SMS activation code (satoshis)     |
| `send`                 | Number | Price to send an SMS message (satoshis)                |
| `rent`                 | Number | Price to rent a phone number (satoshis)                |
| `s4s`                  | String | Platform fee (satoshis)                                |
| `computed.price`       | Number | Exact price for the queried country/service (satoshis) |
| `computed.country`     | Number | Resolved numeric country code                          |
| `computed.description` | String | Human-readable description of the computed order       |

{% hint style="info" %}
Omit `country` and `service` to get generic min/max price ranges. Pass both for an exact price for a specific country/service combination.
{% endhint %}


# Create Receive Order

Create an order to receive an SMS activation code for a phone number.

<mark style="color:green;">`POST`</mark> `https://api2.sms4sats.com/createorder`

Creates a new receive SMS order. Returns an `orderId` and a Lightning invoice (`payreq`). Pay the invoice to activate the order and start waiting for an SMS.

#### Request Body

| Name        | Type    | Required | Description                                                                                                        |
| ----------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------ |
| `country`   | Number  | Yes      | Country code (e.g. `187` for USA). See [Get Countries](/api-reference/get-countries).                              |
| `service`   | String  | Yes      | Service short code (e.g. `vk`). Use `value` from [Get Available Services](/api-reference/get-services).            |
| `isRental`  | Boolean | No       | Set to `true` for a phone number rental order.                                                                     |
| `realphone` | Boolean | No       | Set to `true` for a real phone number from the sms4sats network.                                                   |
| `ref`       | String  | No       | A valid [Lightning Address](https://lightningaddress.com) to receive 10% referral payments for this order.         |
| `immediate` | Boolean | No       | Set to `true` to deduct cost from your API Key balance instead of issuing an invoice. Requires `X-API-Key` header. |

{% tabs %}
{% tab title="200: OK" %}
{% code overflow="wrap" %}

```javascript
{
    status: 'OK', 
    orderId: '7dc6e6b61d8c54dff6b8d6ea2e3f08b018e57963df81d493a6f9728c4dc83318', 
    payreq: 'lnbc30u1p34yef6pp5...'
}
```

{% endcode %}
{% endtab %}

{% tab title="500: Internal Server Error" %}

```javascript
{
    status: 'error',
    reason: 'unable to save data'
}
```

{% endtab %}
{% endtabs %}

### Response Fields

| Field     | Type   | Description                                          |
| --------- | ------ | ---------------------------------------------------- |
| `status`  | String | `OK` on success                                      |
| `orderId` | String | Unique order ID — use this to check status or cancel |
| `payreq`  | String | BOLT11 Lightning invoice to pay                      |

### Next Steps

1. Pay the `payreq` invoice using any Lightning wallet.
2. Poll [Get Order Status](/api-reference/get-order-status) with the `orderId` until `code` appears in the response.
3. Optionally [Cancel Order](/api-reference/cancel-order) after 2 minutes if no code has arrived.

{% hint style="success" %}
sms4sats uses [hold invoices](https://bolt.fun/guide/invoices/hodl-invoice). Payment is only settled when an activation code is successfully delivered. If no code arrives within 21 minutes, the invoice is automatically canceled and funds returned.
{% endhint %}


# Get Order Status

Check the current status of an order and retrieve the activation code once available.

<mark style="color:blue;">`GET`</mark> `https://api2.sms4sats.com/orderstatus`

Returns the current status of a receive or send order. For receive orders, the activation `code` and phone `number` appear in the response once the SMS has been delivered.

#### Query Parameters

| Name      | Type   | Required | Description                                                                                                                           |
| --------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `orderId` | String | Yes      | Order ID returned by [`/createorder`](/api-reference/create-receive-order) or [`/createsendorder`](/api-reference/create-send-order). |

{% tabs %}
{% tab title="200: OK — Receive Order (code received)" %}
{% code overflow="wrap" %}

```javascript
{
    status: 'OK', 
    paid: true, 
    code: 48010,
    id: 1125699791,
    number: 12345678901,
    timestamp: 1666613406969,
    country: 'India',
    service: 'openAI',
}
```

{% endcode %}
{% endtab %}

{% tab title="200: OK — Send Order" %}

```javascript
{
    status: 'OK', 
    paid: true, 
    id: 'SMfa2be998e8913565cbbd5f750e32b1b5',
    smsStatus: 'created | sent | delivered | failed',
    timestamp: 1666613406969,
}
```

{% endtab %}

{% tab title="200: OK — No Number Available" %}

```javascript
{
    status: 'OK', 
    paid: true, 
    error: 'No available number, payment request is canceled. Your funds are returned to your wallet automatically.'
}
```

{% endtab %}

{% tab title="500: Internal Server Error" %}

```javascript
{
    status: 'error',
    reason: 'unable to save data'
}
```

{% endtab %}
{% endtabs %}

### Response Fields

| Field       | Type          | Description                                                            |
| ----------- | ------------- | ---------------------------------------------------------------------- |
| `status`    | String        | `OK` on success                                                        |
| `paid`      | Boolean       | Whether the Lightning invoice has been paid                            |
| `code`      | Number        | The SMS activation code (receive orders only — appears when delivered) |
| `number`    | Number        | The phone number assigned to this order                                |
| `id`        | Number/String | Internal activation ID (receive) or SMS provider ID (send)             |
| `smsStatus` | String        | Send order status: `created`, `sent`, `delivered`, or `failed`         |
| `country`   | String        | Country name                                                           |
| `service`   | String        | Service name                                                           |
| `timestamp` | Number        | Unix timestamp (milliseconds)                                          |
| `error`     | String        | Error message if a number could not be assigned                        |

### Polling

Poll this endpoint every few seconds after paying the invoice. The `code` field will appear once an SMS has been received. Most codes arrive within 30–120 seconds.

{% hint style="warning" %}
If `paid` is `true` but `code` is absent and more than 2 minutes have passed, consider calling [Cancel Order](/api-reference/cancel-order) to free the number and get your funds back.
{% endhint %}


# Cancel Order

Cancel a receive order and release the associated hold invoice.

<mark style="color:blue;">`GET`</mark> `https://api2.sms4sats.com/cancelorder`

Cancels a receive order and releases the associated hold invoice. Your funds are automatically returned to your wallet.

{% hint style="info" %}
You can cancel an order after **2 minutes** if no activation code has arrived. All orders without a received code are **automatically canceled after 21 minutes**.
{% endhint %}

#### Query Parameters

| Name      | Type   | Required | Description                                                                 |
| --------- | ------ | -------- | --------------------------------------------------------------------------- |
| `orderId` | String | Yes      | Order ID returned by [`/createorder`](/api-reference/create-receive-order). |

{% tabs %}
{% tab title="200: OK" %}
{% code overflow="wrap" %}

```javascript
{
    status: 'OK'
}
```

{% endcode %}
{% endtab %}

{% tab title="500: Internal Server Error" %}

```javascript
{
    status: 'error',
    reason: 'unable to save data'
}
```

{% endtab %}
{% endtabs %}

### Response Fields

| Field    | Type   | Description                     |
| -------- | ------ | ------------------------------- |
| `status` | String | `OK` on successful cancellation |

{% hint style="warning" %}
Only orders that have **not** yet received an activation code can be canceled. Once a code is delivered, the invoice is settled and cannot be reversed.
{% endhint %}


# Create Send Order

Create an order to send an SMS message to a phone number.

<mark style="color:green;">`POST`</mark> `https://api2.sms4sats.com/createsendorder`

Creates an order to send an SMS message to any E.164 phone number. Returns a Lightning invoice to pay, or immediately sends the SMS if using a pre-funded API Key.

#### Headers

| Name        | Type   | Required | Description                                                    |
| ----------- | ------ | -------- | -------------------------------------------------------------- |
| `X-API-Key` | String | No       | API Key for pre-funded account. Required if `immediate: true`. |

#### Request Body

| Name         | Type    | Required | Description                                                                                                        |
| ------------ | ------- | -------- | ------------------------------------------------------------------------------------------------------------------ |
| `message`    | String  | Yes      | Message text to send. Maximum 140 characters.                                                                      |
| `phone`      | String  | Yes      | Destination phone number in [E.164 format](https://en.wikipedia.org/wiki/E.164) (e.g. `+19871234567`).             |
| `immediate`  | Boolean | No       | Set to `true` to send immediately and deduct cost from your API Key balance.                                       |
| `webhookUrl` | String  | No       | URL to receive order status updates via `POST`. Same payload as [`/orderstatus`](/api-reference/get-order-status). |

{% tabs %}
{% tab title="200: OK" %}
{% code overflow="wrap" %}

```javascript
{
    status: 'OK', 
    orderId: '7dc6e6b61d8c54dff6b8d6ea2e3f08b018e57963df81d493a6f9728c4dc83318', 
    payreq: 'lnbc30u1p34yef6pp5... | paid'
}
```

{% endcode %}
{% endtab %}

{% tab title="500: Internal Server Error" %}

```javascript
{
    status: 'error',
    reason: 'backend error'
}
```

{% endtab %}
{% endtabs %}

### Response Fields

| Field     | Type   | Description                                                                                      |
| --------- | ------ | ------------------------------------------------------------------------------------------------ |
| `status`  | String | `OK` on success                                                                                  |
| `orderId` | String | Unique order ID — use with [Get Order Status](/api-reference/get-order-status)                   |
| `payreq`  | String | BOLT11 Lightning invoice, or `"paid"` if `immediate: true` and payment was deducted from balance |

### Checking Delivery Status

Use [Get Order Status](/api-reference/get-order-status) with the returned `orderId` to monitor send progress. The `smsStatus` field will reflect `created → sent → delivered` (or `failed`).

{% hint style="success" %}
For send orders, the hold invoice is only settled once the SMS status is `sent` or `delivered`. If delivery fails, the invoice is canceled and funds returned.
{% endhint %}


# Fund Account

Add satoshis to your prepaid API Key balance to skip per-order invoices.

<mark style="color:green;">`POST`</mark> `https://api2.sms4sats.com/fund`

Creates a Lightning invoice to top up a prepaid API Key balance. Once funded, you can use `immediate: true` on order endpoints to skip per-order invoice payment and deduct directly from your balance.

#### Headers

| Name        | Type   | Required | Description           |
| ----------- | ------ | -------- | --------------------- |
| `X-API-Key` | String | Yes      | Your API Key to fund. |

#### Request Body

| Name     | Type   | Required | Description                                |
| -------- | ------ | -------- | ------------------------------------------ |
| `amount` | Number | Yes      | Amount in satoshis to add to your balance. |

{% tabs %}
{% tab title="200: OK" %}
{% code overflow="wrap" %}

```javascript
{
    status: 'OK', 
    orderId: '7dc6e6b61d8c54dff6b8d6ea2e3f08b018e57963df81d493a6f9728c4dc83318', 
    payreq: 'lnbc30u1p34yef6pp5...'
}
```

{% endcode %}
{% endtab %}

{% tab title="500: Internal Server Error" %}

```javascript
{
    status: 'error',
    reason: 'backend error'
}
```

{% endtab %}
{% endtabs %}

### Response Fields

| Field     | Type   | Description                                          |
| --------- | ------ | ---------------------------------------------------- |
| `status`  | String | `OK` on success                                      |
| `orderId` | String | Funding order ID                                     |
| `payreq`  | String | BOLT11 Lightning invoice to pay to fund your balance |

{% hint style="info" %}
Once the invoice is paid, your balance is credited and visible via [Get Balance](/api-reference/get-balance). You can then use `immediate: true` when creating orders to deduct directly without receiving a new invoice each time.

Get in touch for volume discounts: <sales@sms4sats.com>.
{% endhint %}


# Get Balance

Check the current satoshi balance of your prepaid API Key account.

<mark style="color:blue;">`GET`</mark> `https://api2.sms4sats.com/balance`

Returns the current satoshi balance for a prepaid API Key.

#### Headers

| Name        | Type   | Required | Description   |
| ----------- | ------ | -------- | ------------- |
| `X-API-Key` | String | Yes      | Your API Key. |

{% tabs %}
{% tab title="200: OK" %}
{% code overflow="wrap" %}

```javascript
{
    status: 'OK', 
    balance: 10000
}
```

{% endcode %}
{% endtab %}

{% tab title="400: Bad Request" %}

```javascript
{
    status: 'error',
    reason: 'X-API-Key header is missing.'
}
```

{% endtab %}
{% endtabs %}

### Response Fields

| Field     | Type   | Description                 |
| --------- | ------ | --------------------------- |
| `status`  | String | `OK` on success             |
| `balance` | Number | Current balance in satoshis |

{% hint style="info" %}
Use [Fund Account](/api-reference/fund-account) to top up your balance, and [Get History](/api-reference/get-history) to review past funding transactions.
{% endhint %}


# Get History

Retrieve the funding transaction history for your prepaid API Key account.

<mark style="color:blue;">`GET`</mark> `https://api2.sms4sats.com/history`

Returns the complete funding history for a prepaid API Key, including all top-up transactions and their amounts.

#### Headers

| Name        | Type   | Required | Description   |
| ----------- | ------ | -------- | ------------- |
| `X-API-Key` | String | Yes      | Your API Key. |

{% tabs %}
{% tab title="200: OK" %}
{% code overflow="wrap" %}

```javascript
{
  status: 'OK', 
  totalAmount: 349500,
  orders: [ 
    {
      amount: 9500,
      createdAt: 1668612831730,
      desc: 'fund account',
      description: 'fund account',
      holdinvoice: true,
      preimage: 'xxx',
      preimageHash: 'sha256(xxx)',
      price: 9500,
      userId: 'APIKEY'
    },
    ...
  ],
}
```

{% endcode %}
{% endtab %}

{% tab title="400: Bad Request" %}

```javascript
{
    status: 'error',
    reason: 'X-API-Key header is missing.'
}
```

{% endtab %}
{% endtabs %}

### Response Fields

| Field                   | Type    | Description                                      |
| ----------------------- | ------- | ------------------------------------------------ |
| `status`                | String  | `OK` on success                                  |
| `totalAmount`           | Number  | Total satoshis funded across all transactions    |
| `orders`                | Array   | List of funding transactions                     |
| `orders[].amount`       | Number  | Amount funded in this transaction (satoshis)     |
| `orders[].createdAt`    | Number  | Unix timestamp (milliseconds) of the transaction |
| `orders[].description`  | String  | Transaction description                          |
| `orders[].holdinvoice`  | Boolean | Whether this was a hold invoice                  |
| `orders[].preimage`     | String  | Lightning payment preimage                       |
| `orders[].preimageHash` | String  | SHA256 hash of the preimage                      |
| `orders[].price`        | Number  | Price paid (satoshis)                            |
| `orders[].userId`       | String  | The API Key associated with this transaction     |

{% hint style="info" %}
Get in touch for volume discounts: <sales@sms4sats.com>.
{% endhint %}