ShamCash API

HTTP reference for linked ShamCash accounts.

All paths below are relative to this base URL.

HTTP

Base URL:
https://api.shamcash-api.com/v1

Authorization:
Authorization: Bearer <api_token>

Authentication

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

Header

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: Responses use application/json; charset=utf-8. Request bodies, if added later, should use the same type unless documented otherwise.

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.

JSON

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

Name	Type	Description
`status`	string	"success" or "error"
`code`	string	Machine-readable outcome.
`message`	string	Human-readable summary. On success, a short confirmation. On error, what went wrong and what the user can do next.
`data`	mixed	Payload on success. On error often null or [] depending on endpoint.

Success rules: status is "success"; code is "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

Code	Typical HTTP	Meaning
`SUCCESS`	200	Request completed successfully.
`VALIDATION_ERROR`	400	Malformed or conflicting query parameters, for example invalid date format or invalid coin_id.
`AUTH_MISSING`	401	No Authorization header or empty token.
`AUTH_INVALID`	401	Token unknown, expired, or revoked.
`FORBIDDEN`	403	Token valid but not allowed to perform this action.
`NOT_FOUND`	404	Resource not found, for example unknown account_id for this user.
`SUBSCRIPTION_UNAVAILABLE`	403	This operation is not allowed because the account has no active subscription, the subscription period has ended, the ShamCash link is inactive, or subscription data is missing. The exact situation is described in message.
`RATE_LIMIT_EXCEEDED`	429	Too many requests. Retry after the period indicated by Retry-After when present.
`FETCH_FAILED`	502	Upstream or internal data fetch failed. Safe to retry with backoff.
`INTERNAL_ERROR`	500	Unexpected server error.

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

Endpoints

Examples

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

cURL

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

JavaScript

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

<?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']);

Python

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)

Python client

Official Python client for this API.

Install

pip install shamcash

GitHub: Melchersman/shamcash

PyPI: shamcash

Verify package usage from the GitHub or PyPI package documentation.

Error response example

JSON

{
  "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

Bearer token

Endpoint

Query string

Generated cURL

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

Response

No request sent yet.