ShamCash API

HTTP API for ShamCash accounts that users link on shamcash-api.com. A user registers on the platform, attaches one or more ShamCash accounts to their profile, then uses this API to list those accounts, inspect subscription state, read balances, and query incoming transactions.

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

All paths below are relative to that base URL.

---

Authentication

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

Header

Authorization: Bearer <api_token>

Tokens are opaque strings. Treat them as secrets; do not embed them in client-side web code or public repositories.

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

---

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 you pass a full ISO 8601 value with an explicit offset.

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 | 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 (see Error codes).

---

Response envelope

Every response uses the same top-level shape:

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

Success

• status is "success".
• code is "SUCCESS".
• message briefly describes the outcome (for example "Balances retrieved successfully.").
• data follows the schema described for each endpoint.

Error

• status is "error".
• code is one of the values in Error codes.
• message always explains the failure in plain language (validation hint, auth hint, subscription hint, etc.).
• 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.

---

Accounts

GET /accounts

Returns every ShamCash account linked to the authenticated user on the platform.

Response when status is "success"

data is an array of account objects:

{
  "status": "success",
  "code": "SUCCESS",
  "message": "Accounts retrieved successfully.",
  "data": [
    {
      "id": "acc_01hqy8k2example",
      "name": "string",
      "email": "string",
      "phone": "string",
      "status": "active",
      "subscription_expires_at": "2026-12-31T23:59:59+03:00"
    }
  ]
}

Recommended practice: Treat status !== "active" or past subscription_expires_at as “cannot use balances/transactions for this account” until the user renews on the platform.

---

Balances

GET /balances

Returns balance rows for one linked account (three currencies when all are present).

Query parameters

Response when status is "success"

data is an object:

{
  "status": "success",
  "code": "SUCCESS",
  "message": "Balances retrieved successfully.",
  "data": {
    "account_id": "acc_01hqy8k2example",
    "balances": [
      {
        "currency": { "id": 1, "code": "USD" },
        "available": 0.0,
        "blocked": 0.0
      }
    ]
  }
}

---

Transactions

GET /transactions

Returns incoming (received) transactions for a single linked account, with optional filters.

Query parameters are listed in logical order (the order you should document in client code and OpenAPI).

Query parameters

Filtering behavior

1. Scope is always the given account_id for the authenticated user.
2. If start_at / end_at are set, keep only rows whose occurred_at falls in that window (Damascus).
3. If coin_id is set, keep only that currency.
4. If transaction_ids is set, keep only rows whose id is in that set (intersection with the above). If none of the requested ids exist or match the filters, data.transactions is an empty array — still SUCCESS, not an error.
5. limit applies last (e.g. newest first within the filtered set).

Lookup by transaction id

When transaction_ids is provided, the service returns only matching incoming transactions that also satisfy account_id, dates, and coin_id. If no id matches, data.transactions is []. This is expected for idempotent “check these ids” workflows.

Response when status is "success"

{
  "status": "success",
  "code": "SUCCESS",
  "message": "Transactions retrieved successfully.",
  "data": {
    "account_id": "acc_01hqy8k2example",
    "transactions": [
      {
        "transaction_id": 184627893,
        "amount": 0.1,
        "currency": { "id": 1, "code": "USD" },
        "occurred_at": "2026-04-16T01:22:21+03:00",
        "receiver_name": "string",
        "sender_name": "string",
        "sender_address": "string",
        "note": ""
      }
    ]
  }
}

For incoming transfers, receiver_name is the display name of your linked ShamCash account (the account that received funds). sender_name is the display name of the other party, and sender_address is the opaque address identifier returned by the payment network for that party.

---

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 examples of message 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."

---