shamcash 1.0.0

Python client for the ShamCash HTTP API (shamcash-api.com)

shamcash

Python client for the ShamCash HTTP API (accounts linked on shamcash-api.com).

Installation

pip install shamcash

Usage

Async

import asyncio
from shamcash import ShamCashAPI

async def main():
    async with ShamCashAPI(api_token="your_token") as client:
        accounts = await client.list_accounts()
        acc_id = accounts[0].id

        one = await client.get_account(acc_id)
        balances = await client.get_balances(acc_id)

        txs = await client.list_transactions(
            acc_id,
            start_at="2026-01-01",
            end_at="2026-12-31",
            coin_id=1,
            limit=50,
        )

        single = await client.get_transaction(acc_id, 184627893)

asyncio.run(main())

Sync

from shamcash import ShamCashAPISync

with ShamCashAPISync(api_token="your_token") as client:
    accounts = client.list_accounts()
    balances = client.get_balances(accounts[0].id)
    txs = client.list_transactions(accounts[0].id, limit=20)

Filters (GET /transactions)

Optional keyword arguments on list_transactions / list_transactions (sync):

Parameter	Description
start_at	Inclusive lower bound (YYYY-MM-DD or datetime; Asia/Damascus if no offset)
end_at	Inclusive upper bound
transaction_ids	Comma-separated string, one int, or sequence of ids
coin_id	1 USD, 2 SYP, 3 EUR
limit	Max rows (server default 20; server may cap e.g. 200)

Use get_transaction(account_id, transaction_id) to resolve a single incoming transfer by numeric id (uses the transaction_ids filter).

API

ShamCashAPI / ShamCashAPISync

Method	Returns	Description
list_accounts()	List[Account]	All linked accounts
get_account(account_id)	Account	One account by id
get_balances(account_id)	BalancesResult	Per-currency balances
list_transactions(account_id, **filters)	TransactionsResult	Incoming transactions
get_transaction(account_id, transaction_id)	IncomingTransaction | None	One transaction by id
find_transaction_by_id(transactions, transaction_id)	IncomingTransaction | None	Local search in a list

Models

• Account, Currency, BalanceRow, BalancesResult, IncomingTransaction, TransactionsResult — see shamcash.models.

Error handling

Exceptions map to API envelope code values (e.g. AuthInvalidError, AccountNotFoundError, SubscriptionUnavailableError, RateLimitExceededError). Use ShamCashAPIError as the base type. Transport or invalid JSON responses raise NetworkError.

Rate limits

Per linked account: 6 requests per minute for GET /accounts/{id}, GET /balances, and GET /transactions (see API documentation).

License

MIT