POST /api/v1/transactions — Post a Balanced Transaction

The /api/v1/transactions endpoint posts a new double-entry transaction to the ledger. Every transaction must carry at least two journal lines that balance — the sum of all DEBIT amounts must equal the sum of all CREDIT amounts for each currency. A unique Idempotency-Key header is required on every request.

Endpoint

POST /api/v1/transactions

Authorization

Requires an API key with the TRANSACTIONS_WRITE scope. Pass as Authorization: Bearer <key>.

Headers

string

required

A client-generated unique key (max 255 characters) that prevents duplicate transaction posting on retries. If you retry a request with the same key after a successful commit, the original transaction is returned.

Request Body

array

required

Array of journal lines (minimum 2, maximum 1000). Debits must equal credits per currency.

Show Line object

string

required

UUID of the account to post this line to.

string

required

DEBIT or CREDIT.

object

required

The monetary value. Set type to FIAT or ONCHAIN.

Show FiatEntryDto fields

string

required

Must be FIAT.

number

required

Transaction amount.

string

required

BRL, USD, MXN, or EUR.

string

required

ACH, WIRE, PIX, SWIFT, or SEPA.

string

Optional bank reference number.

Show OnChainEntryDto fields

string

required

Must be ONCHAIN.

number

required

Transaction amount.

string

required

USDC, USDT, BRZ, or PYUSD.

string

required

EVM, SOLANA, or TRON.

string

required

On-chain transaction hash.

integer

required

Block number of the transaction.

string

required

Wallet address involved.

string

required

Token contract address.

string

Optional human-readable description for this line.

object

Arbitrary key-value string map attached to the transaction, up to 50 entries. Optional — defaults to an empty map if omitted. Use this to store your own reference data (customer IDs, order numbers, etc.).

The Idempotency-Key is consumed on a successful 201 response. Retrying with the same key returns the original transaction. A 409 means a transaction with that key is still in progress — wait and retry.

Request Examples

On-chain entry
Fiat entry

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-onchain-001" \
  -d '{
    "lines": [
      {
        "accountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "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": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "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",
      "orderId": "ord_12345"
    }
  }'

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-fiat-002" \
  -d '{
    "lines": [
      {
        "accountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "entryType": "DEBIT",
        "monetaryEntry": {
          "type": "FIAT",
          "amount": 500.00,
          "currency": "USD",
          "rail": "ACH",
          "bankReference": "ACH-REF-99123"
        },
        "description": "ACH wire in"
      },
      {
        "accountId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "entryType": "CREDIT",
        "monetaryEntry": {
          "type": "FIAT",
          "amount": 500.00,
          "currency": "USD",
          "rail": "ACH",
          "bankReference": "ACH-REF-99123"
        },
        "description": "Customer USD deposit"
      }
    ],
    "metadata": {
      "customerId": "cust_xyz",
      "source": "bank_transfer"
    }
  }'

Response

string

UUID of the committed transaction.

Response Example

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

Error Codes

A 422 error has two possible causes: (1) Unbalanced transaction — the total DEBIT amount does not equal the total CREDIT amount for a given currency. Check that each currency’s debits and credits sum to the same value. (2) Account not found — one or more accountId values in your lines array do not correspond to an account in your tenant. Verify all account IDs before retrying.

Code	Meaning
400	Missing or invalid `Idempotency-Key`, or malformed request body
401	Missing or invalid API key
403	API key does not have `TRANSACTIONS_WRITE` scope
409	A transaction with this `Idempotency-Key` is already in progress
422	Account not found, or debits do not equal credits per currency

Accounts

Transactions

Settlements

Reconciliation

Compliance

Administration

POST /api/v1/transactions — Post a Balanced Transaction

Endpoint

Authorization

Headers

Request Body

Request Examples

Response

Response Example

Error Codes

​Endpoint

​Authorization

​Headers

​Request Body

​Request Examples

​Response

​Response Example

​Error Codes

Endpoint

Authorization

Headers

Request Body

Request Examples

Response

Response Example

Error Codes