Strings

A string links single-currency ledgers into one group and moves value between them atomically.

Endpoints

Method	Path	Description
GET	`/strings`	List ledger strings for the tenant
POST	`/strings`	Create a ledger string
GET	`/strings/{code}`	Get a ledger string with its member ledgers
GET	`/strings/{code}/accounts`	List accounts across all member ledgers of a string
GET	`/strings/{code}/accounts/{accountCode}/balance`	Unified per-ledger balance for an account code across a string
POST	`/strings/{stringCode}/transfer`	Post an atomic same-currency transfer between two member ledgers of a string
POST	`/strings/{stringCode}/convert`	Post an atomic different-currency conversion between two member ledgers of a string

Transfer between member ledgers

Same currency, no rate. Both legs post in one database transaction. The key must belong to a member ledger and carry strings:participate:{stringCode}.

curl -X POST https://ledga.io/api/v1/strings/treasury-fx/transfer \
  -H "Authorization: Bearer sk_xxxxxxxx_your_secret" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: xfer-2026-0001" \
  -d '{
    "source_ledger_code": "gbp-main",
    "target_ledger_code": "gbp-reserve",
    "account_code": "2100",
    "amount": "250.00",
    "reference": "XFER-0001"
  }'

Convert between currencies

source_amount and target_amount are both authoritative; rate is recorded for audit only.

curl -X POST https://ledga.io/api/v1/strings/treasury-fx/convert \
  -H "Authorization: Bearer sk_xxxxxxxx_your_secret" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: conv-2026-0001" \
  -d '{
    "source_ledger_code": "gbp-main",
    "target_ledger_code": "usd-main",
    "account_code": "2100",
    "source_amount": "100.00",
    "target_amount": "127.40",
    "rate": "1.274",
    "reference": "CONV-0001"
  }'

Rules

POST /strings creates a string. Membership is not managed through this API; GET /strings/{code} lists the member ledgers.
GET /strings/{code}/accounts lists accounts across every member ledger; …/accounts/{accountCode}/balance returns a per-ledger balance for one code.
A replayed Idempotency-Key returns 200 with the original result.

The PHP SDK does not cover string endpoints yet. Use HTTP directly.