Post your first transaction

Five calls take you from nothing to a posted transaction and a balance you can read back. Every one of them matches the API reference.

Wrong page? This is the ledger: accounts, postings, balances, reconciliation. If you are here to decide whether your software may spend before it does, start with Kordio Control: authorize an agent action.

The base URL is https://api.kordio.io. OAuth lives at /oauth/token; ledger resources live under /ledger/v1.

1. Get your client credentials

Create an OAuth client from the dashboard, or use one seeded for you in development. A client has a client_id, a client_secret (shown once), a mode (test or live), and a set of granted scopes. Read operations need ledger:read; writes need ledger:write, and neither implies the other.

2. Mint an access token

Exchange your credentials for a short-lived token using the client_credentials grant. Send the credentials as HTTP Basic auth.

export KORDIO_TOKEN=$(curl -s -X POST https://api.kordio.io/oauth/token \
  -u "$KORDIO_CLIENT_ID:$KORDIO_CLIENT_SECRET" \
  -d 'grant_type=client_credentials&scope=ledger:read ledger:write' \
  | jq -r '.access_token')

200 OK

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "ledger:read ledger:write"
}

The token carries your tenant, mode, and scopes, and is valid for one hour. There is no ?test= flag: the client’s mode decides whether you touch test or live data. See Authentication for the full flow.

3. Create two accounts

An account is a named bucket of value in one currency. You choose the id. Create one asset account and one revenue account, both in USD.

curl -X POST https://api.kordio.io/ledger/v1/accounts \
  -H "Authorization: Bearer $KORDIO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id":"cash:usd","name":"Cash","type":"asset","currency":"USD"}'

curl -X POST https://api.kordio.io/ledger/v1/accounts \
  -H "Authorization: Bearer $KORDIO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id":"revenue:subscriptions","name":"Subscriptions","type":"revenue","currency":"USD"}'

Each call returns the created account inside the standard envelope:

{
  "data": {
    "object": "account",
    "id": "cash:usd",
    "name": "Cash",
    "type": "asset",
    "currency": "USD",
    "currency_decimals": 2,
    "currency_kind": "fiat",
    "metadata": {},
    "created_at": "2026-05-14T10:23:45.123456Z"
  },
  "livemode": false,
  "request_id": "req_3LhM8XKx9q4hQv"
}

4. Post a balanced transaction

A transaction is a set of postings that balance per currency. Move 10.00 USD (1000 minor units) from cash into revenue. Writes require an Idempotency-Key so retries never double-post.

curl -X POST https://api.kordio.io/ledger/v1/transactions \
  -H "Authorization: Bearer $KORDIO_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: invoice_001" \
  -d '{"postings":[
        {"account":"cash:usd","amount":"1000","currency":"USD","direction":"debit"},
        {"account":"revenue:subscriptions","amount":"1000","currency":"USD","direction":"credit"}
      ]}'

Amounts are JSON strings of integer minor units. Parse them with a big-integer type, never a JS number. The response includes the transaction and its postings:

{
  "object": "transaction",
  "id": "3061ec4e-c959-49ba-a0f6-99186a7bd5d8",
  "idempotency_key": "invoice_001",
  "reverses": null,
  "reversed_by": null,
  "metadata": {},
  "postings": [
    { "object": "posting", "account": "cash:usd", "amount": "1000", "currency": "USD", "direction": "debit", "pending": false },
    { "object": "posting", "account": "revenue:subscriptions", "amount": "1000", "currency": "USD", "direction": "credit", "pending": false }
  ],
  "created_at": "2026-05-14T15:53:31.291591Z"
}

Replaying the same Idempotency-Key returns this same transaction with a 200 and an Idempotent-Replayed: true header, instead of creating a new one. It returns the original whatever you sent the second time, so give a different transaction a different key. To validate a transaction without writing it, add ?dry_run=true and omit the idempotency key.

5. Read the balance

Balances are derived from the postings rather than stored, so this number is recomputed from what you just wrote:

curl https://api.kordio.io/ledger/v1/accounts/cash:usd/balance \
  -H "Authorization: Bearer $KORDIO_TOKEN"

200 OK

{
  "data": {
    "object": "balance",
    "account": "cash:usd",
    "currency": "USD",
    "currency_decimals": 2,
    "posted": "1000",
    "pending": "0",
    "available": "1000"
  },
  "livemode": false,
  "request_id": "req_..."
}

You can read a historical balance by passing ?at=<ISO 8601 timestamp>, which computes the balance from each posting’s value_date. See value-date semantics.

Next steps

Core concepts

Double-entry, corrections, idempotency, multi-currency, and value dates.

Webhooks

Subscribe to events, verify signatures, and replay from the events tail.

Pagination and expand

Walk list endpoints with cursors and inline related objects.

API reference

Every endpoint, generated from the OpenAPI spec.

Get started

Core concepts

Guarantees

Reference

Endpoints

Post your first transaction

1. Get your client credentials

2. Mint an access token

3. Create two accounts

4. Post a balanced transaction

5. Read the balance

Next steps

Core concepts

Webhooks

Pagination and expand

API reference

​1. Get your client credentials

​2. Mint an access token

​3. Create two accounts

​4. Post a balanced transaction

​5. Read the balance

​Next steps

Core concepts

Webhooks

Pagination and expand

API reference

1. Get your client credentials

2. Mint an access token

3. Create two accounts

4. Post a balanced transaction

5. Read the balance

Next steps