Documentation

Quickstart

Authentication

The API authenticates with a secret key sent as a bearer token. Live keys are prefixed sk_live_ and test keys sk_test_. Keys carry scopes; a key without the write scope can read balances but cannot post entries.

Never ship a live key to a browser or mobile client. Rotate from the dashboard under Developers → API keys; a rotated key stops working immediately.

Your first transfer

POST /v1/transfers

curl https://api.tallyspan.xyz/v1/transfers \
  -H "Authorization: Bearer sk_live_…" \
  -d "amount=4200" \
  -d "currency=usd" \
  -d "from=acct_18fJq2" \
  -d "to=acct_9dK01x" \
  -d "idempotency_key=8f2c1a"

Errors

Errors return a JSON object with code, message and request_id. Include the request id in any support thread. Authentication failures return 401; a key that is valid but lacks the required scope returns 403.

401 Unauthorized

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid credentials.",
    "request_id": "6d85e709-7248-4dbf-8723-27e91b24ae1e"
  }
}

Rate limits

Requests are limited per key. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Exceeding the limit returns 429 with Retry-After.