BuyShazam Developer API

Automate orders with your BuyShazam wallet

Use the BuyShazam API to list services, place wallet-paid orders, and track status from your own app.

Manage API Access API Base URL https://auto.buyshazam.com

The API Base URL is the server address your app sends API requests to. Add endpoint paths like /api/v1/services or /api/v1/orders after this URL.

Authentication

Every request must include your API key, a Unix timestamp, and an HMAC SHA256 signature.

signature = HMAC_SHA256(secret, method + "\n" + path + "\n" + timestamp + "\n" + body_sha256)

X-API-Key: your API key.
X-Timestamp: current Unix timestamp. Requests are valid for 5 minutes.
X-Signature: hex HMAC, optionally prefixed with sha256=.
X-Idempotency-Key: required for order creation to prevent duplicate charges.

Endpoint overview

GET /api/v1/balance

Check wallet balance for the authenticated API account.

GET /api/v1/services

List available services, public service IDs, and public prices.

POST /api/v1/orders

Create a wallet-paid order.

GET /api/v1/orders/{id}

Check one API order.

GET /api/v1/orders

List recent API orders.

Endpoint details

GET /api/v1/balance

Returns the BuyShazam Wallet balance for the API account.

Body: None
Response: balance, currency, woo_customer_id

GET /api/v1/services

Returns the services your account can order. Use the returned id as service_id when creating an order.

price_per_1000 is the public BuyShazam selling price per 1,000 units.

Body: None
Response: services[].id, name, category, price_per_1000, price_per_unit, currency, min, max, type

POST /api/v1/orders

Creates a BuyShazam Wallet paid order. Include X-Idempotency-Key in the headers to prevent duplicate orders if your request is retried.

Required: service_id, quantity, link
Optional: client_order_ref, custom_comments
Response: order.id, woo_order_number, status, charge

GET /api/v1/orders/{id}

Returns one API order by the API order ID, for example BSAPI-ABC123DEF456.

Body: None
Response: order.status, smm_status, charge, currency

GET /api/v1/orders

Lists recent API orders. Supports page, limit, and status query parameters.

Example: /api/v1/orders?page=1&limit=50
Response: orders[], page, limit, total

Create order payload

This payload is enough for standard services. For custom comment services, also send custom_comments. The service_id must come from GET /api/v1/services.

Estimated charge is price_per_1000 * quantity / 1000. The confirmed charged amount is returned as order.charge.

{
  "service_id": 123,
  "quantity": 1000,
  "link": "https://www.tiktok.com/@username/video/123",
  "client_order_ref": "your-order-10001",
  "custom_comments": "Great post!\nAmazing content!"
}

custom_comments is optional. Omit it for standard services.

Examples

PHP 7.4 example: create order

<?php
$baseUrl = 'https://auto.buyshazam.com';
$apiKey = 'bs_live_xxx';
$apiSecret = 'your_api_secret';
$method = 'POST';
$path = '/api/v1/orders';
$body = json_encode([
    'service_id' => 123,
    'quantity' => 1000,
    'link' => 'https://www.tiktok.com/@username/video/123'
]);
$timestamp = time();
$bodyHash = hash('sha256', $body);
$message = implode("\n", [$method, $path, $timestamp, $bodyHash]);
$signature = hash_hmac('sha256', $message, $apiSecret);

$ch = curl_init($baseUrl . $path);
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'X-API-Key: ' . $apiKey,
        'X-Timestamp: ' . $timestamp,
        'X-Signature: sha256=' . $signature,
        'X-Idempotency-Key: order-' . time(),
    ],
    CURLOPT_POSTFIELDS => $body,
]);
echo curl_exec($ch);

Python example: create order

import hashlib
import hmac
import json
import time
import uuid

import requests

BASE_URL = "https://auto.buyshazam.com"
API_KEY = "bs_live_xxx"
API_SECRET = "your_api_secret"

method = "POST"
path = "/api/v1/orders"
body = json.dumps({
    "service_id": 123,
    "quantity": 1000,
    "link": "https://www.tiktok.com/@username/video/123",
    "client_order_ref": "your-order-10001",
}, separators=(",", ":"))

timestamp = str(int(time.time()))
body_hash = hashlib.sha256(body.encode("utf-8")).hexdigest()
message = "\n".join([method, path, timestamp, body_hash])
signature = hmac.new(
    API_SECRET.encode("utf-8"),
    message.encode("utf-8"),
    hashlib.sha256,
).hexdigest()

response = requests.post(
    BASE_URL + path,
    data=body,
    headers={
        "Content-Type": "application/json",
        "X-API-Key": API_KEY,
        "X-Timestamp": timestamp,
        "X-Signature": "sha256=" + signature,
        "X-Idempotency-Key": "order-" + str(uuid.uuid4()),
    },
    timeout=30,
)
print(response.status_code)
print(response.json())

Rust example: create order

// Cargo.toml dependencies:
// hmac = "0.12"
// reqwest = { version = "0.12", features = ["blocking"] }
// serde_json = "1"
// sha2 = "0.10"

use hmac::{Hmac, Mac};
use reqwest::blocking::Client;
use serde_json::json;
use sha2::{Digest, Sha256};
use std::time::{SystemTime, UNIX_EPOCH};

type HmacSha256 = Hmac<Sha256>;

fn hex(bytes: &[u8]) -> String {
    bytes.iter().map(|b| format!("{:02x}", b)).collect()
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let base_url = "https://auto.buyshazam.com";
    let api_key = "bs_live_xxx";
    let api_secret = "your_api_secret";
    let method = "POST";
    let path = "/api/v1/orders";
    let body = json!({
        "service_id": 123,
        "quantity": 1000,
        "link": "https://www.tiktok.com/@username/video/123",
        "client_order_ref": "your-order-10001"
    }).to_string();

    let timestamp = SystemTime::now()
        .duration_since(UNIX_EPOCH)?
        .as_secs()
        .to_string();
    let body_hash = hex(&Sha256::digest(body.as_bytes()));
    let message = format!("{}\n{}\n{}\n{}", method, path, timestamp, body_hash);

    let mut mac = HmacSha256::new_from_slice(api_secret.as_bytes())?;
    mac.update(message.as_bytes());
    let signature = hex(&mac.finalize().into_bytes());

    let response = Client::new()
        .post(format!("{}{}", base_url, path))
        .header("Content-Type", "application/json")
        .header("X-API-Key", api_key)
        .header("X-Timestamp", timestamp)
        .header("X-Signature", format!("sha256={}", signature))
        .header("X-Idempotency-Key", format!("order-{}", SystemTime::now().duration_since(UNIX_EPOCH)?.as_nanos()))
        .body(body)
        .send()?;

    println!("{}", response.status());
    println!("{}", response.text()?);
    Ok(())
}

C# example: create order

using System;
using System.Net.Http;
using System.Security.Cryptography;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        var baseUrl = "https://auto.buyshazam.com";
        var apiKey = "bs_live_xxx";
        var apiSecret = "your_api_secret";
        var method = "POST";
        var path = "/api/v1/orders";
        var body = "{\"service_id\":123,\"quantity\":1000,\"link\":\"https://www.tiktok.com/@username/video/123\",\"client_order_ref\":\"your-order-10001\"}";

        var timestamp = DateTimeOffset.UtcNow.ToUnixTimeSeconds().ToString();
        var bodyHash = Sha256Hex(body);
        var message = string.Join("\n", method, path, timestamp, bodyHash);
        var signature = HmacSha256Hex(apiSecret, message);

        using (var client = new HttpClient())
        using (var request = new HttpRequestMessage(HttpMethod.Post, baseUrl + path))
        {
            request.Content = new StringContent(body, Encoding.UTF8, "application/json");
            request.Headers.Add("X-API-Key", apiKey);
            request.Headers.Add("X-Timestamp", timestamp);
            request.Headers.Add("X-Signature", "sha256=" + signature);
            request.Headers.Add("X-Idempotency-Key", "order-" + Guid.NewGuid().ToString("N"));

            var response = await client.SendAsync(request);
            Console.WriteLine((int)response.StatusCode);
            Console.WriteLine(await response.Content.ReadAsStringAsync());
        }
    }

    static string Sha256Hex(string value)
    {
        using (var sha256 = SHA256.Create())
        {
            return ToHex(sha256.ComputeHash(Encoding.UTF8.GetBytes(value)));
        }
    }

    static string HmacSha256Hex(string secret, string value)
    {
        using (var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret)))
        {
            return ToHex(hmac.ComputeHash(Encoding.UTF8.GetBytes(value)));
        }
    }

    static string ToHex(byte[] bytes)
    {
        return BitConverter.ToString(bytes).Replace("-", "").ToLowerInvariant();
    }
}

Java example: create order

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.time.Instant;
import java.util.UUID;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public class BuyShazamCreateOrder {
    public static void main(String[] args) throws Exception {
        String baseUrl = "https://auto.buyshazam.com";
        String apiKey = "bs_live_xxx";
        String apiSecret = "your_api_secret";
        String method = "POST";
        String path = "/api/v1/orders";
        String body = "{\"service_id\":123,\"quantity\":1000,\"link\":\"https://www.tiktok.com/@username/video/123\",\"client_order_ref\":\"your-order-10001\"}";

        String timestamp = String.valueOf(Instant.now().getEpochSecond());
        String bodyHash = sha256Hex(body);
        String message = String.join("\n", method, path, timestamp, bodyHash);
        String signature = hmacSha256Hex(apiSecret, message);

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(baseUrl + path))
            .header("Content-Type", "application/json")
            .header("X-API-Key", apiKey)
            .header("X-Timestamp", timestamp)
            .header("X-Signature", "sha256=" + signature)
            .header("X-Idempotency-Key", "order-" + UUID.randomUUID())
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.statusCode());
        System.out.println(response.body());
    }

    static String sha256Hex(String value) throws Exception {
        MessageDigest digest = MessageDigest.getInstance("SHA-256");
        return hex(digest.digest(value.getBytes(StandardCharsets.UTF_8)));
    }

    static String hmacSha256Hex(String secret, String value) throws Exception {
        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
        return hex(mac.doFinal(value.getBytes(StandardCharsets.UTF_8)));
    }

    static String hex(byte[] bytes) {
        StringBuilder out = new StringBuilder();
        for (byte b : bytes) {
            out.append(String.format("%02x", b));
        }
        return out.toString();
    }
}

Ruby example: create order

require "digest"
require "json"
require "net/http"
require "openssl"
require "securerandom"
require "time"

base_url = "https://auto.buyshazam.com"
api_key = "bs_live_xxx"
api_secret = "your_api_secret"
method = "POST"
path = "/api/v1/orders"
body = {
  service_id: 123,
  quantity: 1000,
  link: "https://www.tiktok.com/@username/video/123",
  client_order_ref: "your-order-10001"
}.to_json

timestamp = Time.now.to_i.to_s
body_hash = Digest::SHA256.hexdigest(body)
message = [method, path, timestamp, body_hash].join("\n")
signature = OpenSSL::HMAC.hexdigest("SHA256", api_secret, message)

uri = URI(base_url + path)
request = Net::HTTP::Post.new(uri)
request["Content-Type"] = "application/json"
request["X-API-Key"] = api_key
request["X-Timestamp"] = timestamp
request["X-Signature"] = "sha256=#{signature}"
request["X-Idempotency-Key"] = "order-#{SecureRandom.uuid}"
request.body = body

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts response.code
puts response.body

Go example: create order

package main

import (
	"bytes"
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"fmt"
	"io"
	"net/http"
	"strings"
	"time"
)

func main() {
	baseURL := "https://auto.buyshazam.com"
	apiKey := "bs_live_xxx"
	apiSecret := "your_api_secret"
	method := "POST"
	path := "/api/v1/orders"
	body := `{"service_id":123,"quantity":1000,"link":"https://www.tiktok.com/@username/video/123","client_order_ref":"your-order-10001"}`

	timestamp := fmt.Sprintf("%d", time.Now().Unix())
	bodyHash := sha256Hex(body)
	message := strings.Join([]string{method, path, timestamp, bodyHash}, "\n")
	signature := hmacSha256Hex(apiSecret, message)

	req, err := http.NewRequest(method, baseURL+path, bytes.NewBufferString(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("X-API-Key", apiKey)
	req.Header.Set("X-Timestamp", timestamp)
	req.Header.Set("X-Signature", "sha256="+signature)
	req.Header.Set("X-Idempotency-Key", fmt.Sprintf("order-%d", time.Now().UnixNano()))

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	data, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.StatusCode)
	fmt.Println(string(data))
}

func sha256Hex(value string) string {
	sum := sha256.Sum256([]byte(value))
	return hex.EncodeToString(sum[:])
}

func hmacSha256Hex(secret, value string) string {
	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write([]byte(value))
	return hex.EncodeToString(mac.Sum(nil))
}

Swift example: create order

import CryptoKit
import Foundation

let baseUrl = "https://auto.buyshazam.com"
let apiKey = "bs_live_xxx"
let apiSecret = "your_api_secret"
let method = "POST"
let path = "/api/v1/orders"
let body = #"{"service_id":123,"quantity":1000,"link":"https://www.tiktok.com/@username/video/123","client_order_ref":"your-order-10001"}"#

func hex<S: Sequence>(_ bytes: S) -> String where S.Element == UInt8 {
    bytes.map { String(format: "%02x", $0) }.joined()
}

let timestamp = String(Int(Date().timeIntervalSince1970))
let bodyHash = hex(SHA256.hash(data: Data(body.utf8)))
let message = [method, path, timestamp, bodyHash].joined(separator: "\n")
let key = SymmetricKey(data: Data(apiSecret.utf8))
let signature = hex(HMAC<SHA256>.authenticationCode(for: Data(message.utf8), using: key))

var request = URLRequest(url: URL(string: baseUrl + path)!)
request.httpMethod = method
request.httpBody = Data(body.utf8)
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
request.setValue(apiKey, forHTTPHeaderField: "X-API-Key")
request.setValue(timestamp, forHTTPHeaderField: "X-Timestamp")
request.setValue("sha256=\(signature)", forHTTPHeaderField: "X-Signature")
request.setValue("order-\(UUID().uuidString)", forHTTPHeaderField: "X-Idempotency-Key")

let task = URLSession.shared.dataTask(with: request) { data, response, error in
    if let error = error {
        print(error)
        return
    }
    if let http = response as? HTTPURLResponse {
        print(http.statusCode)
    }
    if let data = data, let text = String(data: data, encoding: .utf8) {
        print(text)
    }
}
task.resume()
RunLoop.main.run()

C++ example: create order

#include <curl/curl.h>
#include <openssl/hmac.h>
#include <openssl/sha.h>
#include <ctime>
#include <iomanip>
#include <iostream>
#include <sstream>
#include <string>

std::string hex(const unsigned char* data, size_t len) {
    std::ostringstream out;
    for (size_t i = 0; i < len; ++i) {
        out << std::hex << std::setw(2) << std::setfill('0') << static_cast<int>(data[i]);
    }
    return out.str();
}

std::string sha256Hex(const std::string& value) {
    unsigned char hash[SHA256_DIGEST_LENGTH];
    SHA256(reinterpret_cast<const unsigned char*>(value.c_str()), value.size(), hash);
    return hex(hash, SHA256_DIGEST_LENGTH);
}

std::string hmacSha256Hex(const std::string& secret, const std::string& value) {
    unsigned int len = SHA256_DIGEST_LENGTH;
    unsigned char hash[SHA256_DIGEST_LENGTH];
    HMAC(EVP_sha256(), secret.c_str(), static_cast<int>(secret.size()),
         reinterpret_cast<const unsigned char*>(value.c_str()), value.size(), hash, &len);
    return hex(hash, len);
}

int main() {
    std::string baseUrl = "https://auto.buyshazam.com";
    std::string apiKey = "bs_live_xxx";
    std::string apiSecret = "your_api_secret";
    std::string method = "POST";
    std::string path = "/api/v1/orders";
    std::string body = R"({"service_id":123,"quantity":1000,"link":"https://www.tiktok.com/@username/video/123","client_order_ref":"your-order-10001"})";

    std::string timestamp = std::to_string(std::time(nullptr));
    std::string bodyHash = sha256Hex(body);
    std::string message = method + "\n" + path + "\n" + timestamp + "\n" + bodyHash;
    std::string signature = hmacSha256Hex(apiSecret, message);

    CURL* curl = curl_easy_init();
    if (!curl) {
        return 1;
    }

    struct curl_slist* headers = nullptr;
    headers = curl_slist_append(headers, "Content-Type: application/json");
    headers = curl_slist_append(headers, ("X-API-Key: " + apiKey).c_str());
    headers = curl_slist_append(headers, ("X-Timestamp: " + timestamp).c_str());
    headers = curl_slist_append(headers, ("X-Signature: sha256=" + signature).c_str());
    headers = curl_slist_append(headers, ("X-Idempotency-Key: order-" + timestamp).c_str());

    curl_easy_setopt(curl, CURLOPT_URL, (baseUrl + path).c_str());
    curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
    curl_easy_setopt(curl, CURLOPT_POSTFIELDS, body.c_str());

    CURLcode result = curl_easy_perform(curl);
    std::cout << "\nResult: " << result << std::endl;

    curl_slist_free_all(headers);
    curl_easy_cleanup(curl);
    return 0;
}

cURL example: check wallet balance

curl -X GET "https://auto.buyshazam.com/api/v1/balance" \
  -H "X-API-Key: bs_live_xxx" \
  -H "X-Timestamp: 1710000000" \
  -H "X-Signature: sha256=<hmac_sha256>"

cURL example: list services

curl -X GET "https://auto.buyshazam.com/api/v1/services" \
  -H "X-API-Key: bs_live_xxx" \
  -H "X-Timestamp: 1710000000" \
  -H "X-Signature: sha256=<hmac_sha256>"

cURL example: check order status

curl -X GET "https://auto.buyshazam.com/api/v1/orders/BSAPI-ABC123DEF456" \
  -H "X-API-Key: bs_live_xxx" \
  -H "X-Timestamp: 1710000000" \
  -H "X-Signature: sha256=<hmac_sha256>"

Error codes

API errors return success: false and an error code. Some validation errors also include useful fields such as min, max, balance, required, or details.

Error	HTTP	Meaning
`missing_auth_headers`	401	`X-API-Key`, `X-Timestamp`, or `X-Signature` is missing.
`invalid_api_key`	401	The API key is invalid, disabled, revoked, or not active.
`invalid_timestamp`	401	`X-Timestamp` is not a valid Unix timestamp.
`timestamp_out_of_range`	401	The timestamp is older or newer than the allowed 5-minute window.
`invalid_signature`	401	The HMAC signature is invalid for the method, path, timestamp, and body hash.
`ip_not_allowed`	403	The request IP is not in the API key's allowed IP list.
`rate_limited`	429	The API key exceeded its per-minute request limit.
`missing_idempotency_key`	400	Order creation requires `X-Idempotency-Key`.
`invalid_service_or_quantity`	400	`service_id` or `quantity` is missing or invalid.
`missing_link`	400	The order link is required.
`service_not_found`	404	The requested service ID does not exist or is not active.
`service_not_allowed`	403	The API account is not allowed to order this service.
`quantity_below_minimum`	400	The requested quantity is below the service minimum. Response includes `min`.
`quantity_above_maximum`	400	The requested quantity is above the service maximum. Response includes `max`.
`duplicate_order`	409	The idempotency key or client order reference conflicts with an existing order.
`order_not_found`	404	The API order ID was not found for this API account.
`insufficient_wallet_balance`	402	The BuyShazam Wallet does not have enough credit. Response includes `balance`, `required`, and `currency`.
`customer_wallet_locked`	409	Another wallet-paid API order is being processed. Retry shortly with the same idempotency key.
`customer_not_found`	404	The customer linked to the API key could not be found.
`product_not_found`	404	The selected service is temporarily unavailable in the store.
`product_not_available`	404	The matched store product is not published or available.
`invalid_price`	422	The order price could not be calculated.
`terawallet_not_active`	503	The wallet payment service is temporarily unavailable.
`wallet_debit_failed`	500	The wallet debit failed while creating the order.
`wallet_debit_exception`	500	The wallet debit process raised an unexpected error.
`wallet_debit_unavailable`	500	No supported wallet debit method is available.
`order_create_failed`	500	The order could not be created.
`service_pricing_unavailable`	502/503	Public service pricing could not be loaded from the store.
`woo_not_configured`	503	The BuyShazam API server cannot connect to the Woo store configuration.
`woo_not_active`	503	Woo is temporarily unavailable on the store.
`internal_api_not_configured`	503	The internal BuyShazam API connection is not configured.
`invalid_internal_signature`	401	The internal BuyShazam API connection failed authentication. Contact support.
`internal_timestamp_out_of_range`	401	The internal BuyShazam API server clocks are out of sync. Contact support.
`rest_forbidden`	403	The internal store endpoint rejected the API request. Contact support.
`invalid_wallet_response`	502	The wallet balance endpoint returned an invalid response.
`wallet_balance_failed`	502	The wallet balance check failed.
`invalid_order_response`	502	The order creation backend returned an invalid response.
`order_creation_failed`	502	The order creation backend rejected the order without a more specific code.
`database_unavailable`	503	The API database is temporarily unavailable.
`auth_error`	500	An unexpected authentication error occurred.