Quickstart: Post Your First Idem Ledger Transaction

The Idem Ledger API uses double-entry bookkeeping — every transaction must have at least two journal lines where debits equal credits. This quickstart walks you through getting your API key, creating two accounts, posting a balanced transaction, and verifying the resulting balance.

Idem is open source (FSL-1.1-ALv2) and can be self-hosted, run against the managed cloud, or shipped as the enterprise distribution. The examples below use https://api.your-domain.com as a placeholder — swap it for your Idem base URL (for example, http://localhost:8080 if you’re running the docker-compose stack locally).

Get your API key

Provision (or generate) an admin API key for your tenant. Idem API keys have the format sk_live_{uuid} and are shown exactly once. Set it as an environment variable:

export IDEM_API_KEY=sk_live_your_key_here
export IDEM_API_URL=https://api.your-domain.com

See Authentication for details on creating additional scoped keys for different integrations.

Create two accounts

Every transaction needs accounts to post to. Create an ASSET account (representing a wallet you hold) and a LIABILITY account (representing what you owe to customers):

# Create an asset account (e.g., stablecoin custodial wallet)
curl -X POST https://api.your-domain.com/api/v1/accounts \
  -H "Authorization: Bearer $IDEM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "USDC Wallet",
    "description": "Primary USDC custodial wallet",
    "currency": "USD",
    "type": "ASSET"
  }'

# Create a liability account (e.g., customer deposits)
curl -X POST https://api.your-domain.com/api/v1/accounts \
  -H "Authorization: Bearer $IDEM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Deposits",
    "description": "Customer deposit liability",
    "currency": "USD",
    "type": "LIABILITY"
  }'

Each response returns an id UUID. Save both:

export ASSET_ACCOUNT_ID=<id from first response>
export LIABILITY_ACCOUNT_ID=<id from second response>

Account currency and type are immutable after creation. Choose carefully.

Post a balanced transaction

Post a two-line transaction: DEBIT the asset account (value coming in) and CREDIT the liability account (obligation created). The Idempotency-Key header prevents duplicate posts on retries.

curl -X POST https://api.your-domain.com/api/v1/transactions \
  -H "Authorization: Bearer $IDEM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: txn-quickstart-001" \
  -d '{
    "lines": [
      {
        "accountId": "'"$ASSET_ACCOUNT_ID"'",
        "entryType": "DEBIT",
        "monetaryEntry": {
          "type": "ONCHAIN",
          "amount": 100.00,
          "token": "USDC",
          "chainId": "EVM",
          "txHash": "0xabc123def456...",
          "blockNumber": 19500000,
          "walletAddress": "0xYourCustodialWallet...",
          "tokenContract": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
        },
        "description": "Incoming USDC deposit"
      },
      {
        "accountId": "'"$LIABILITY_ACCOUNT_ID"'",
        "entryType": "CREDIT",
        "monetaryEntry": {
          "type": "ONCHAIN",
          "amount": 100.00,
          "token": "USDC",
          "chainId": "EVM",
          "txHash": "0xabc123def456...",
          "blockNumber": 19500000,
          "walletAddress": "0xYourCustodialWallet...",
          "tokenContract": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
        },
        "description": "Customer deposit credit"
      }
    ],
    "metadata": {
      "customerId": "cust_abc",
      "source": "quickstart"
    }
  }'

A successful 201 response returns the committed transaction ID:

{
  "transactionId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
}

If you retry with the same Idempotency-Key after a success, you get the original result back — no duplicate is posted.

Verify the balance

Confirm the transaction posted by checking the asset account balance:

curl "https://api.your-domain.com/api/v1/accounts/$ASSET_ACCOUNT_ID/balance" \
  -H "Authorization: Bearer $IDEM_API_KEY"

Expected response:

{
  "accountId": "...",
  "currency": "USD",
  "amount": 100.00,
  "normalBalance": "DEBIT",
  "computedAt": "2024-01-15T10:30:05Z"
}

Check the liability account balance too — it should show 100.00 as well, confirming the double-entry invariant holds.

Next steps

Double-Entry Concepts

Understand the full journal line model, fiat vs. on-chain entries, and the balance invariant.

Settlements

Reconciliation

Re-run matching for transactions that weren’t reconciled on initial commit.

Authentication

Create scoped API keys for different integrations using least-privilege access.

Code Examples

Kotlin reference implementations covering most Idem features, including the MCP client.

Get Started

Core Concepts

Guides

Quickstart: Post Your First Idem Ledger Transaction

Next steps

Double-Entry Concepts

Settlements

Reconciliation

Authentication

Code Examples

​Next steps

Double-Entry Concepts

Settlements

Reconciliation

Authentication

Code Examples

Next steps