API docs

Quickstart

1. Create a platform account and obtain an API token from your dashboard.
2. Create a linking session on your server, display its QR, and poll until the account is linked. Activate a trial or paid plan separately.
3. Send your first request from your server using the token.

curl "https://api.shamcash-api.com/v1/accounts" \
  -H "Authorization: Bearer <api_token>" \
  -H "Accept: application/json"

Authentication

Every request must include a valid API token issued from the platform dashboard.

Authorization: Bearer <api_token>

If the token is missing, invalid, or revoked, the API returns status: "error" with an appropriate code and a human-readable message.

Conventions

Versioning: The v1 path segment is the current major version. Incompatible changes will be introduced under v2, v3, and so on.

Content type: Send JSON request bodies with Content-Type: application/json. Responses use application/json.

Time zones: For /transactions query parameters, start_at and end_at are interpreted in Asia/Damascus unless a full ISO 8601 value with an explicit offset is provided. Transaction objects return occurred_at as an ISO 8601 timestamp with offset, for example 2026-04-16T01:22:21+03:00.

Account lifecycle: Each item under /accounts is a ShamCash account the user linked on the platform. It has a status, active or inactive, and optional subscription_expires_at describing when API access for that link ends. If the user calls /balances or /transactions when the link is inactive, there is no subscription, or the subscription period has ended, the API returns SUBSCRIPTION_UNAVAILABLE.

Response envelope

Every response uses this top-level shape.

{
  "status": "success",
  "code": "SUCCESS",
  "message": "Accounts retrieved successfully.",
  "data": {}
}

Success rules:status is "success"; code is "SUCCESS" or an endpoint-specific code such as "LINK_SUCCESS"; message briefly describes the outcome; data follows the schema described for each endpoint.

Error rules:status is "error"; code is one of the documented error codes; message explains the failure; data is typically null or an empty array; clients should use code for branching and message for display or logging.

Error codes

Exact HTTP status for a given code may be tuned per deployment. Use status, code, message, and data for client logic.

Account linking and subscriptions

An optional way to handle linking, subscription purchases, renewals and account management in your application instead of sending users to the dashboard for each step. The wallet owner still scans and approves the QR in ShamCash.

Enable account and subscription management on the API-token page first. Accounts belong to the token owner, and subscription purchases debit that owner's platform USD wallet.

Examples

Examples use server-side code. Do not put API tokens in browser code.

curl "https://api.shamcash-api.com/v1/accounts" \
  -H "Authorization: Bearer <api_token>" \
  -H "Accept: application/json"

const API_BASE = "https://api.shamcash-api.com/v1";
const token = process.env.SHAMCASH_API_TOKEN;

async function listAccounts() {
  const response = await fetch(`${API_BASE}/accounts`, {
    headers: {
      Authorization: `Bearer ${token}`,
      Accept: "application/json"
    }
  });

  const payload = await response.json();

  if (!response.ok || payload.status !== "success") {
    throw new Error(`${payload.code}: ${payload.message}`);
  }

  return payload.data;
}

<?php

$apiBase = 'https://api.shamcash-api.com/v1';
$token = getenv('SHAMCASH_API_TOKEN');

$ch = curl_init($apiBase . '/accounts');

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $token,
        'Accept: application/json',
    ],
    CURLOPT_TIMEOUT => 30,
]);

$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);

if ($body === false) {
    throw new RuntimeException(curl_error($ch));
}

curl_close($ch);

$payload = json_decode($body, true);

if ($status >= 400 || ($payload['status'] ?? null) !== 'success') {
    throw new RuntimeException(($payload['code'] ?? 'ERROR') . ': ' . ($payload['message'] ?? 'Request failed'));
}

print_r($payload['data']);

import os
import requests

API_BASE = "https://api.shamcash-api.com/v1"
TOKEN = os.environ["SHAMCASH_API_TOKEN"]

def shamcash_get(path, params=None):
    response = requests.get(
        f"{API_BASE}{path}",
        headers={
            "Authorization": f"Bearer {TOKEN}",
            "Accept": "application/json",
        },
        params=params or {},
        timeout=30,
    )

    payload = response.json()

    if response.status_code >= 400 or payload.get("status") != "success":
        raise RuntimeError(f"{payload.get('code')}: {payload.get('message')}")

    return payload["data"]

accounts = shamcash_get("/accounts")
account_id = accounts[0]["id"]

balances = shamcash_get("/balances", {"account_id": account_id})
transactions = shamcash_get("/transactions", {
    "account_id": account_id,
    "start_at": "2026-05-25",
    "limit": 20,
})

print(accounts)
print(balances)
print(transactions)

Error response example

{
  "status": "error",
  "code": "SUBSCRIPTION_UNAVAILABLE",
  "message": "This account has no active subscription. Purchase or renew a plan on shamcash-api.com to use balances and transactions.",
  "data": null
}

Other possible messages for the same code:

• "The subscription for this account ended on 2026-01-01. Renew on shamcash-api.com to continue."
• "This ShamCash link is inactive. Reactivate it in your dashboard to continue."
• "No subscription is associated with this account."

API tester

curl "https://api.shamcash-api.com/v1/accounts" \
  -H "Authorization: Bearer <api_token>" \
  -H "Accept: application/json"

No request sent yet.

Python library

Official Python client for this API.

pip install shamcash

GitHub: Melchersman/shamcash

PyPI: shamcash