sms4sats API Documentation

Send or Receive SMS programmatically, pay with Lightning.

Instructions on how to use sms4sats.com API to generate sms activation code orders from anywhere, pay with Lightning Bitcoin and receive the activation codes.

Contact

Telegram: pseudozach or https://t.me/sms4sats

Email: [email protected]

Twitter: https://twitter.com/sms4sats

Node Info

Feel free to open a direct channel to our node if you have trouble with routing or let us know and we're happy to open balanced channels to high volume partners.

Postman

You can easily run the API in postman to understand the parameters and responses by clicking below.

API info

API root is at: https://api2.sms4sats.com. You can also use this endpoint to check for availability.

You may need to use below country code list to map country names into country codes and send this code in certain queries. Normally, API should work with inputs such as country="germany".

Country Code List

const countrymap = [
 {
   "cc": 999,
   "country": "Auto-Select"
 },
 {
   "cc": 0,
   "country": "Russia"
 },
 {
   "cc": 0,
   "country": "Russian"
 },
 {
   "cc": 1,
   "country": "Ukraine"
 },
 {
   "cc": 2,
   "country": "Kazakhstan"
 },
 {
   "cc": 3,
   "country": "China"
 },
 {
   "cc": 4,
   "country": "Philippines"
 },
 {
   "cc": 5,
   "country": "Myanmar"
 },
 {
   "cc": 6,
   "country": "Indonesia"
 },
 {
   "cc": 7,
   "country": "Malaysia"
 },
 {
   "cc": 8,
   "country": "Kenya"
 },
 {
   "cc": 9,
   "country": "Tanzania"
 },
 {
   "cc": 10,
   "country": "Vietnam"
 },
 {
   "cc": 11,
   "country": "Kyrgyzstan"
 },
 {
   "cc": 12,
   "country": "USA (virtual)"
 },
 {
   "cc": 13,
   "country": "Israel"
 },
 {
   "cc": 14,
   "country": "HongKong"
 },
 {
   "cc": 15,
   "country": "Poland"
 },
 {
   "cc": 16,
   "country": "England"
 },
 {
   "cc": 16,
   "country": "United Kingdom"
 },
 {
   "cc": 18,
   "country": "DCongo"
 },
 {
   "cc": 19,
   "country": "Nigeria"
 },
 {
   "cc": 20,
   "country": "Macao"
 },
 {
   "cc": 21,
   "country": "Egypt"
 },
 {
   "cc": 22,
   "country": "India"
 },
 {
   "cc": 23,
   "country": "Ireland"
 },
 {
   "cc": 24,
   "country": "Cambodia"
 },
 {
   "cc": 25,
   "country": "Laos"
 },
 {
   "cc": 26,
   "country": "Haiti"
 },
 {
   "cc": 27,
   "country": "Ivory"
 },
 {
   "cc": 28,
   "country": "Gambia"
 },
 {
   "cc": 29,
   "country": "Serbia"
 },
 {
   "cc": 30,
   "country": "Yemen"
 },
 {
   "cc": 31,
   "country": "Southafrica"
 },
 {
   "cc": 32,
   "country": "Romania"
 },
 {
   "cc": 33,
   "country": "Colombia"
 },
 {
   "cc": 34,
   "country": "Estonia"
 },
 {
   "cc": 36,
   "country": "Canada"
 },
 {
   "cc": 37,
   "country": "Morocco"
 },
 {
   "cc": 38,
   "country": "Ghana"
 },
 {
   "cc": 39,
   "country": "Argentina"
 },
 {
   "cc": 40,
   "country": "Uzbekistan"
 },
 {
   "cc": 41,
   "country": "Cameroon"
 },
 {
   "cc": 42,
   "country": "Chad"
 },
 {
   "cc": 43,
   "country": "Germany"
 },
 {
   "cc": 44,
   "country": "Lithuania"
 },
 {
   "cc": 45,
   "country": "Croatia"
 },
 {
   "cc": 46,
   "country": "Sweden"
 },
 {
   "cc": 47,
   "country": "Iraq"
 },
 {
   "cc": 48,
   "country": "Netherlands"
 },
 {
   "cc": 49,
   "country": "Latvia"
 },
 {
   "cc": 50,
   "country": "Austria"
 },
 {
   "cc": 51,
   "country": "Belarus"
 },
 {
   "cc": 52,
   "country": "Thailand"
 },
 {
   "cc": 53,
   "country": "Saudiarabia"
 },
 {
   "cc": 54,
   "country": "Mexico"
 },
 {
   "cc": 55,
   "country": "Taiwan"
 },
 {
   "cc": 56,
   "country": "Spain"
 },
 {
   "cc": 58,
   "country": "Algeria"
 },
 {
   "cc": 59,
   "country": "Slovenia"
 },
 {
   "cc": 60,
   "country": "Bangladesh"
 },
 {
   "cc": 61,
   "country": "Senegal"
 },
 {
   "cc": 62,
   "country": "Turkey"
 },
 {
   "cc": 63,
   "country": "Czech"
 },
 {
   "cc": 64,
   "country": "Srilanka"
 },
 {
   "cc": 65,
   "country": "Peru"
 },
 {
   "cc": 66,
   "country": "Pakistan"
 },
 {
   "cc": 67,
   "country": "Newzealand"
 },
 {
   "cc": 68,
   "country": "Guinea"
 },
 {
   "cc": 69,
   "country": "Mali"
 },
 {
   "cc": 70,
   "country": "Venezuela"
 },
 {
   "cc": 71,
   "country": "Ethiopia"
 },
 {
   "cc": 72,
   "country": "Mongolia"
 },
 {
   "cc": 73,
   "country": "Brazil"
 },
 {
   "cc": 74,
   "country": "Afghanistan"
 },
 {
   "cc": 75,
   "country": "Uganda"
 },
 {
   "cc": 76,
   "country": "Angola"
 },
 {
   "cc": 77,
   "country": "Cyprus"
 },
 {
   "cc": 78,
   "country": "France"
 },
 {
   "cc": 79,
   "country": "Papua"
 },
 {
   "cc": 80,
   "country": "Mozambique"
 },
 {
   "cc": 81,
   "country": "Nepal"
 },
 {
   "cc": 82,
   "country": "Belgium"
 },
 {
   "cc": 83,
   "country": "Bulgaria"
 },
 {
   "cc": 84,
   "country": "Hungary"
 },
 {
   "cc": 85,
   "country": "Moldova"
 },
 {
   "cc": 86,
   "country": "Italy"
 },
 {
   "cc": 87,
   "country": "Paraguay"
 },
 {
   "cc": 88,
   "country": "Honduras"
 },
 {
   "cc": 89,
   "country": "Tunisia"
 },
 {
   "cc": 90,
   "country": "Nicaragua"
 },
 {
   "cc": 91,
   "country": "Timorleste"
 },
 {
   "cc": 92,
   "country": "Bolivia"
 },
 {
   "cc": 93,
   "country": "Costarica"
 },
 {
   "cc": 94,
   "country": "Guatemala"
 },
 {
   "cc": 95,
   "country": "Uae"
 },
 {
   "cc": 96,
   "country": "Zimbabwe"
 },
 {
   "cc": 97,
   "country": "Puertorico"
 },
 {
   "cc": 99,
   "country": "Togo"
 },
 {
   "cc": 100,
   "country": "Kuwait"
 },
 {
   "cc": 101,
   "country": "Salvador"
 },
 {
   "cc": 102,
   "country": "Libyan"
 },
 {
   "cc": 103,
   "country": "Jamaica"
 },
 {
   "cc": 104,
   "country": "Trinidad"
 },
 {
   "cc": 105,
   "country": "Ecuador"
 },
 {
   "cc": 106,
   "country": "Swaziland"
 },
 {
   "cc": 107,
   "country": "Oman"
 },
 {
   "cc": 108,
   "country": "Bosnia"
 },
 {
   "cc": 109,
   "country": "Dominican"
 },
 {
   "cc": 111,
   "country": "Qatar"
 },
 {
   "cc": 112,
   "country": "Panama"
 },
 {
   "cc": 114,
   "country": "Mauritania"
 },
 {
   "cc": 115,
   "country": "Sierraleone"
 },
 {
   "cc": 116,
   "country": "Jordan"
 },
 {
   "cc": 117,
   "country": "Portugal"
 },
 {
   "cc": 118,
   "country": "Barbados"
 },
 {
   "cc": 119,
   "country": "Burundi"
 },
 {
   "cc": 120,
   "country": "Benin"
 },
 {
   "cc": 121,
   "country": "Brunei"
 },
 {
   "cc": 122,
   "country": "Bahamas"
 },
 {
   "cc": 123,
   "country": "Botswana"
 },
 {
   "cc": 124,
   "country": "Belize"
 },
 {
   "cc": 125,
   "country": "Caf"
 },
 {
   "cc": 126,
   "country": "Dominica"
 },
 {
   "cc": 127,
   "country": "Grenada"
 },
 {
   "cc": 128,
   "country": "Georgia"
 },
 {
   "cc": 129,
   "country": "Greece"
 },
 {
   "cc": 130,
   "country": "Guineabissau"
 },
 {
   "cc": 131,
   "country": "Guyana"
 },
 {
   "cc": 132,
   "country": "Iceland"
 },
 {
   "cc": 133,
   "country": "Comoros"
 },
 {
   "cc": 134,
   "country": "Saintkitts"
 },
 {
   "cc": 135,
   "country": "Liberia"
 },
 {
   "cc": 136,
   "country": "Lesotho"
 },
 {
   "cc": 137,
   "country": "Malawi"
 },
 {
   "cc": 138,
   "country": "Namibia"
 },
 {
   "cc": 139,
   "country": "Niger"
 },
 {
   "cc": 140,
   "country": "Rwanda"
 },
 {
   "cc": 141,
   "country": "Slovakia"
 },
 {
   "cc": 142,
   "country": "Suriname"
 },
 {
   "cc": 143,
   "country": "Tajikistan"
 },
 {
   "cc": 144,
   "country": "Monaco"
 },
 {
   "cc": 145,
   "country": "Bahrain"
 },
 {
   "cc": 146,
   "country": "Reunion"
 },
 {
   "cc": 147,
   "country": "Zambia"
 },
 {
   "cc": 148,
   "country": "Armenia"
 },
 {
   "cc": 149,
   "country": "Somalia"
 },
 {
   "cc": 150,
   "country": "Congo"
 },
 {
   "cc": 151,
   "country": "Chile"
 },
 {
   "cc": 152,
   "country": "Furkinafaso"
 },
 {
   "cc": 153,
   "country": "Lebanon"
 },
 {
   "cc": 154,
   "country": "Gabon"
 },
 {
   "cc": 155,
   "country": "Albania"
 },
 {
   "cc": 156,
   "country": "Uruguay"
 },
 {
   "cc": 157,
   "country": "Mauritius"
 },
 {
   "cc": 158,
   "country": "Bhutan"
 },
 {
   "cc": 159,
   "country": "Maldives"
 },
 {
   "cc": 160,
   "country": "Guadeloupe"
 },
 {
   "cc": 161,
   "country": "Turkmenistan"
 },
 {
   "cc": 162,
   "country": "Frenchguiana"
 },
 {
   "cc": 163,
   "country": "Finland"
 },
 {
   "cc": 164,
   "country": "Saintlucia"
 },
 {
   "cc": 165,
   "country": "Luxembourg"
 },
 {
   "cc": 166,
   "country": "Saintvincentgrenadines"
 },
 {
   "cc": 167,
   "country": "Equatorialguinea"
 },
 {
   "cc": 168,
   "country": "Djibouti"
 },
 {
   "cc": 169,
   "country": "Antiguabarbuda"
 },
 {
   "cc": 170,
   "country": "Caymanislands"
 },
 {
   "cc": 171,
   "country": "Montenegro"
 },
 {
   "cc": 173,
   "country": "Switzerland"
 },
 {
   "cc": 174,
   "country": "Norway"
 },
 {
   "cc": 175,
   "country": "Australia"
 },
 {
   "cc": 176,
   "country": "Eritrea"
 },
 {
   "cc": 177,
   "country": "Southsudan"
 },
 {
   "cc": 178,
   "country": "Saotomeandprincipe"
 },
 {
   "cc": 179,
   "country": "Aruba"
 },
 {
   "cc": 180,
   "country": "Montserrat"
 },
 {
   "cc": 181,
   "country": "Anguilla"
 },
 {
   "cc": 183,
   "country": "Northmacedonia"
 },
 {
   "cc": 184,
   "country": "Seychelles"
 },
 {
   "cc": 185,
   "country": "Newcaledonia"
 },
 {
   "cc": 186,
   "country": "Capeverde"
 },
 {
   "cc": 187,
   "country": "USA"
 },
 {
   "cc": 187,
   "country": "United States"
 },
 {
  "cc": 187,
  "country": "United States of America"
 },
 {
  "cc": 189,
  "country": "Fiji"
 },
 {
   "cc": 190,
   "country": "Southkorea"
 },
 {
   "cc": 195,
   "country": "Bermuda"
 },
 {
   "cc": 196,
   "country": "Singapore"
 }
];

Getting Prices

Use this endpoint to check the price (in satoshis) that user will need to pay to use services offered by this API.

Get Receive/Send/Rent Price (in satoshis)

GET https://api2.sms4sats.com/price

Note that at the moment, receive and send prices are static but this may change in the future. Rent price will vary based on country.

Query Parameters

Name

Type

Description

country

Number

service

String

{
      receive: 3000, //standard sms activation code price
      send: 1000, // standard sms send price
      rent: 15000, // minimum phone rental price (receive unlimited sms for 4 hours)
      s4s: 5000, // real phone numbers part of sms4sats network
}

Getting Available Services

Use this endpoint to check for available numbers to receive activation codes for each offered service for a specific country.

Get Available Services

GET https://api2.sms4sats.com/getnumbersstatus

Get an array of available services that can be ordered for a country.

Query Parameters

Name

Type

Description

country*

Number

Country Code (e.g. 187 for USA)

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

Creating a Receive Order

Use this endpoint to create a receive SMS order for a specific country and service.

Create Receive Order

POST https://api2.sms4sats.com/createorder

Create an sms4sats order to be fulfilled.

Request Body

Name

Type

Description

country*

Number

Country Code (e.g. 187 for USA)

service*

String

Short Code (e.g. vk for vk.com)

Refer to `value` field in response fromGetting Available Services

isRental

Boolean

set to true if this is for a phone number rental order

realphone

Boolean

set to true if this is for a real phone number that is part of sms4sats network

ref

String

A valid lightning address where you want to receive Referral Payments for the order. (Currently %10)

immediate

Boolean

Set to true if you want to deduct the cost of receive from your API Key balance.

{
    status: 'OK', 
    orderId: '7dc6e6b61d8c54dff6b8d6ea2e3f08b018e57963df81d493a6f9728c4dc83318', 
    payreq: 'lnbc30u1p34yef6pp50hrwddsa332dla4c6m4zu0cgkqvw27trm7qafyaxl9egcnwgxvvqdp5wdkhxdrnv968xgrsv9uk6etwwssywetjd4sku7fqw3mkjar5v4eqcqzpgxqyz5vqsp5fnj032qs6fuht2p3r245h3u6r9x32fhdw5n4qyn7mqm95jt0ag5q9qyyssqlyeyhnqq4y6l5ynxatvnqg6zldnqmwxx7qel0q79slfv7wvuk23zm2shczj4vxf39a4s8x36k9dxcgtnvwdv0j8uq4jcuq3yclw393sp8uywdc'
}

sms4sats uses hold invoices for payment, this means:

When invoice is paid by the user, it's not finalized but HELD by the sms4sats Lightning Node.
For receive orders, Only when an activation code is successfully received the invoice is SETTLED.
For send orders, Only when SMS status is "sent or delivered" the invoice is SETTLED.
If no code is received within 20 minutes, invoice will be CANCELED and funds will automatically return to user's wallet.

Getting Order Status

Use this endpoint to check the status of an order

Get Order Status

GET https://api2.sms4sats.com/orderstatus

Check an sms4sats order status.

Query Parameters

Name

Type

Description

orderId*

String

Order ID returned by the `/createorder` or `/createsendorder` endpoint

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

Canceling a Receive Order

Use this endpoint to cancel a receive order after 2 minutes in case no sms is received.

Note: all orders without a code will be automatically canceled after 21 minutes.

Cancel Order

GET https://api2.sms4sats.com/cancelorder

Cancel an sms4sats order and the hold invoice related to it.

Query Parameters

Name

Type

Description

orderId*

String

Order ID returned by the `/createorder` endpoint

{
    status: 'OK'
}

Creating SMS Send Order

Use this endpoint to create a send SMS order for a phone number and message.

Create SMS Send Order

POST https://api2.sms4sats.com/createsendorder

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

Headers

Name

Type

Description

X-API-Key

String

Optional API Key to use if you want to use a pre-funded account to immediately send the SMS.

Request Body

Name

Type

Description

message*

String

Message text that you want to send to the phone number.

Max 140 characters.

phone*

String

A valid E.164 phone number (e.g. +19871234567)

immediate

Boolean

Set to true if you want to immediately send the SMS and deduct the cost from your API Key balance.

webhookUrl

String

Webhook URL where you want to receive order updates.

Same data as /orderstatus will be sent as POST to this URL.

{
    status: 'OK', 
    orderId: '7dc6e6b61d8c54dff6b8d6ea2e3f08b018e57963df81d493a6f9728c4dc83318', 
    payreq: 'lnbc30u1p34yef6pp50hrwddsa332dla4c6m4zu0cgkqvw27trm7qafyaxl9egcnwgxvvqdp5wdkhxdrnv968xgrsv9uk6etwwssywetjd4sku7fqw3mkjar5v4eqcqzpgxqyz5vqsp5fnj032qs6fuht2p3r245h3u6r9x32fhdw5n4qyn7mqm95jt0ag5q9qyyssqlyeyhnqq4y6l5ynxatvnqg6zldnqmwxx7qel0q79slfv7wvuk23zm2shczj4vxf39a4s8x36k9dxcgtnvwdv0j8uq4jcuq3yclw393sp8uywdc | paid'
}

Creating Email Send Order

Use this endpoint to create a send Email order for an email address and message.

Create Email Send Order

POST https://api2.sms4sats.com/createemailsendorder

Create an sms4sats order to send an Email message to an email address.

Headers

Name

Type

Description

X-API-Key

String

Optional API Key to use if you want to use a pre-funded account to immediately send the SMS.

Request Body

Name

Type

Description

message*

String

Message text that you want to send to the phone number.

Max 140 characters.

address*

String

A valid email address (e.g. [email protected])

immediate

Boolean

Set to true if you want to immediately send the SMS and deduct the cost from your API Key balance.

webhookUrl

String

Webhook URL where you want to receive order updates.

Same data as /orderstatus will be sent as POST to this URL.

{
    status: 'OK', 
    orderId: '7dc6e6b61d8c54dff6b8d6ea2e3f08b018e57963df81d493a6f9728c4dc83318', 
    payreq: 'lnbc30u1p34yef6pp50hrwddsa332dla4c6m4zu0cgkqvw27trm7qafyaxl9egcnwgxvvqdp5wdkhxdrnv968xgrsv9uk6etwwssywetjd4sku7fqw3mkjar5v4eqcqzpgxqyz5vqsp5fnj032qs6fuht2p3r245h3u6r9x32fhdw5n4qyn7mqm95jt0ag5q9qyyssqlyeyhnqq4y6l5ynxatvnqg6zldnqmwxx7qel0q79slfv7wvuk23zm2shczj4vxf39a4s8x36k9dxcgtnvwdv0j8uq4jcuq3yclw393sp8uywdc | paid'
}

Funding an Account

If you have an API Key, you can fund your prepaid balance using this endpoint.

Create Fund Order

POST https://api2.sms4sats.com/fund

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

Headers

Name

Type

Description

X-API-Key*

String

Optional API Key to use if you want to use a pre-funded account to immediately send or receive SMS.

Request Body

Name

Type

Description

amount*

Number

Amount in satoshis you want to fund.

{
    status: 'OK', 
    orderId: '7dc6e6b61d8c54dff6b8d6ea2e3f08b018e57963df81d493a6f9728c4dc83318', 
    payreq: 'lnbc30u1p34yef6pp50hrwddsa332dla4c6m4zu0cgkqvw27trm7qafyaxl9egcnwgxvvqdp5wdkhxdrnv968xgrsv9uk6etwwssywetjd4sku7fqw3mkjar5v4eqcqzpgxqyz5vqsp5fnj032qs6fuht2p3r245h3u6r9x32fhdw5n4qyn7mqm95jt0ag5q9qyyssqlyeyhnqq4y6l5ynxatvnqg6zldnqmwxx7qel0q79slfv7wvuk23zm2shczj4vxf39a4s8x36k9dxcgtnvwdv0j8uq4jcuq3yclw393sp8uywdc'
}

Getting Account Balance

Use this endpoint to check the balance of an account

Get Balance

GET https://api2.sms4sats.com/balance

Get balance for an API Key

Headers

Name

Type

Description

X-API-Key*

String

API Key that was previously funded.

{
    status: 'OK', 
    balance: 10000
}

Getting Account History

Use this endpoint to check the funding history of an account

Get History

GET https://api2.sms4sats.com/history

Get funding history for an API Key

Headers

Name

Type

Description

X-API-Key*

String

API Key that was previously funded.

{
  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'
    },
    ...
  ],
}

Get in touch for volume discounts: [email protected].

Last updated 1 year ago

hashtagNode Info

hashtagPostman

hashtagAPI info

hashtagGetting Prices

hashtagGet Receive/Send/Rent Price (in satoshis)

hashtagQuery Parameters

hashtagGetting Available Services

hashtagGet Available Services

hashtagQuery Parameters

hashtagCreating a Receive Order

hashtagCreate Receive Order

hashtagRequest Body

hashtagGetting Order Status

hashtagGet Order Status

hashtagQuery Parameters

hashtagCanceling a Receive Order

hashtagCancel Order

hashtagQuery Parameters

hashtagCreating SMS Send Order

hashtagCreate SMS Send Order

hashtagHeaders

hashtagRequest Body

hashtagCreating Email Send Order

hashtagCreate Email Send Order

hashtagHeaders

hashtagRequest Body

hashtagFunding an Account

hashtagCreate Fund Order

hashtagHeaders

hashtagRequest Body

hashtagGetting Account Balance

hashtagGet Balance

hashtagHeaders

hashtagGetting Account History

hashtagGet History

hashtagHeaders

Node Info

Postman

API info

Getting Prices

Get Receive/Send/Rent Price (in satoshis)

Query Parameters

Getting Available Services

Get Available Services

Query Parameters

Creating a Receive Order

Create Receive Order

Request Body

Getting Order Status

Get Order Status

Query Parameters

Canceling a Receive Order

Cancel Order

Query Parameters

Creating SMS Send Order

Create SMS Send Order

Headers

Request Body

Creating Email Send Order

Create Email Send Order

Headers

Request Body

Funding an Account

Create Fund Order

Headers

Request Body

Getting Account Balance

Get Balance

Headers

Getting Account History

Get History

Headers