Skip to main content
Flomisma

Settlement Ledger API

Primitives, not platforms.

Tier 2 primitives: immutable ledger entries, settlement fee calculation, contract state machine, and invoice generation — as direct API calls. No custody, no fund transmission. Your money moves through your own Stripe or bank rails; Flomisma records the entries. Vault and Pipeline Integrity (Tier 3) deploy via enterprise field-of-use license — not documented in this public reference.

Authentication & routing

All portal routes use the /api/v1 prefix. Do not use legacy /v1/… paths or Authorization: Bearer — they are not supported.

  • Tier 2 ledger: x-ledger-api-key — settlement, contracts, invoices
  • M2M licensed operators: x-flomisma-api-key — licensee arbitration, HITL override, provision-tenant
  • Public verification: no auth — /verifier (proxies /api/v1/pipeline/verify)

Ledger entries

Append an immutable entry to the GAAP-compliant audit ledger. Every entry triggers an integrity snapshot for SOC2 Processing Integrity.

curl
1# Append an immutable ledger entry
2curl -X POST https://flomisma-platform-core.vercel.app/api/v1/ledger/entries \
3  -H "x-ledger-api-key: your_key" \
4  -H "Content-Type: application/json" \
5  -d '{
6    "tenantId": "tenant_abc",
7    "debit_account": "PLATFORM_REVENUE",
8    "credit_account": "PARTNER_BALANCE",
9    "transaction_type": "SETTLEMENT",
10    "amount": 5000,
11    "reference_id": "order_abc123",
12    "metadata_json": { "description": "Q2 platform fee settlement" }
13  }'
14
15# Response
16# { "success": true, "data": { "entryId": "clx..." } }▋

Settlement calculation

Preview platform fees and net USD settlement amounts. No money moves — this is a calculation engine for your own fiat settlement workflows. Micro-tasks under $10 use a flat $0.15 fee; larger amounts use basis points.

curl
1# Preview USD settlement fee calculation (no money moves)
2curl -X POST https://flomisma-platform-core.vercel.app/api/v1/ledger/calculate-settlement \
3  -H "x-ledger-api-key: your_key" \
4  -H "Content-Type: application/json" \
5  -d '{
6    "contractId": "order_abc123",
7    "tenantId": "tenant_abc",
8    "amount": 5000,
9    "currency": "USD",
10    "settlementMethod": "FIAT",
11    "feeBasisPoints": 25,
12    "isRevenueEnabled": true,
13    "isMicroTask": false,
14    "partyAId": "platform"
15  }'
16
17# Response
18# { "success": true, "data": { "platformFeeAmount": 12.5, "netSettlementAmount": 4987.5, "txRef": "USD-order_abc123-..." } }▋

Contracts (state machine)

Create and manage contracts through a DRAFT → FUNDS_RELEASED state machine. Contracts record terms and track milestone completion. No fund custody — Flomisma records the accounting entries; you move the actual money through your own payment rails.

curl
1# Create a ledger contract (records terms, no fund custody)
2curl -X POST https://flomisma-platform-core.vercel.app/api/v1/ledger/contracts \
3  -H "x-ledger-api-key: your_key" \
4  -H "Content-Type: application/json" \
5  -d '{
6    "tenantId": "tenant_abc",
7    "partyAId": "platform",
8    "partyBId": "partner_xyz",
9    "escrowAmount": 5000,
10    "milestones": [
11      { "title": "Milestone 1 — design complete" },
12      { "title": "Milestone 2 — implementation" }
13    ]
14  }'
15
16# Response
17# { "success": true, "data": { "id": "clx...", "contractId": "LEDGER-ABCD1234", "state": "DRAFT", "escrowAmount": 5000 } }
18
19# List contracts
20curl https://flomisma-platform-core.vercel.app/api/v1/ledger/contracts?tenantId=tenant_abc \
21  -H "x-ledger-api-key: your_key"▋

Release & settlement

Record a release against a contract. Idempotent — same idempotencyKey returns the existing result without re-applying. On full release, an invoice PDF is auto-generated for USD contracts.

curl
1# Record a release (actual money moves through your own Stripe/bank rails)
2curl -X POST https://flomisma-platform-core.vercel.app/api/v1/ledger/contracts/CONTRACT_ID/release \
3  -H "x-ledger-api-key: your_key" \
4  -H "Content-Type: application/json" \
5  -d '{
6    "amount": 5000,
7    "idempotencyKey": "release_abc123_unique",
8    "releaseType": "FULL"
9  }'
10
11# Response
12# { "success": true, "data": { "operationId": "clx...", "newReleased": 5000, "state": "FUNDS_RELEASED" } }▋

Agent settlement (four-call flow)

Programmable agent escrow on the off-chain ledger — not on-chain as system of record. Create → prove → verify → settle. Deterministic policies auto-release; ambiguous work routes to HITL. See /agent-settlement.

1 — create + fund
1# 1 — Create agent task and record escrow funded (ledger state; funds held by your processor)
2curl -X POST https://flomisma-platform-core.vercel.app/api/v1/agent/settlement/create \
3  -H "x-ledger-api-key: your_key" \
4  -H "Content-Type: application/json" \
5  -d '{
6    "tenantId": "tenant_abc",
7    "partyAId": "parent-agent",
8    "partyBId": "worker-agent",
9    "escrowAmount": 25,
10    "policyId": "minimum_rows_v1",
11    "policyParams": { "minRows": 10 }
12  }'
13
14# { "contractId": "AGENT-…", "state": "ESCROW_FUNDED", "settlementRail": "off_chain_ledger" }▋
2 — submit proof
1# 2 — Submit machine-readable proof
2curl -X POST https://flomisma-platform-core.vercel.app/api/v1/agent/proof \
3  -H "x-ledger-api-key: your_key" \
4  -H "Content-Type: application/json" \
5  -d '{
6    "tenantId": "tenant_abc",
7    "contractId": "AGENT-…",
8    "proofString": "json:sha256:…",
9    "payload": { "rows": [ … ] }
10  }'▋
3 — verify queue
1# 3 — Verification queue (stable reviewStatus enums)
2curl -X POST https://flomisma-platform-core.vercel.app/api/v1/agent/verify \
3  -H "x-ledger-api-key: your_key" \
4  -H "Content-Type: application/json" \
5  -d '{
6    "tenantId": "tenant_abc",
7    "contractId": "AGENT-…",
8    "payload": { "rows": [ … ] }
9  }'
10
11# { "status": "queued", "reviewStatus": "AUTO_RELEASE_ELIGIBLE", "hitlRequired": false, … }▋
4 — settle
1# 4 — Settle (release on ledger rails)
2curl -X POST https://flomisma-platform-core.vercel.app/api/v1/agent/settlement/settle \
3  -H "x-ledger-api-key: your_key" \
4  -H "Content-Type: application/json" \
5  -d '{
6    "tenantId": "tenant_abc",
7    "contractId": "AGENT-…",
8    "idempotencyKey": "settle_unique_key_1"
9  }'▋
@flomisma/licensee-sdk
1import {
2  generateProofHash,
3  createAgentTask,
4  submitAgentProof,
5  queueAgentVerification,
6  settleAgentTask,
7  verifyPipelineByContractId,
8} from '@flomisma/licensee-sdk'
9
10const payload = { rows: Array.from({ length: 12 }, (_, i) => ({ id: i })) }
11const proofString = generateProofHash(payload)
12
13const { contractId } = await createAgentTask({
14  tenantId: 'tenant_abc',
15  partyAId: 'parent-agent',
16  partyBId: 'worker-agent',
17  escrowAmount: 25,
18  policyId: 'minimum_rows_v1',
19  policyParams: { minRows: 10 },
20})
21
22await submitAgentProof({ tenantId: 'tenant_abc', contractId, payload, proofString })
23const queue = await queueAgentVerification({ tenantId: 'tenant_abc', contractId, payload })
24
25if (queue?.reviewStatus === 'AUTO_RELEASE_ELIGIBLE') {
26  await settleAgentTask({ tenantId: 'tenant_abc', contractId, idempotencyKey: 'settle_1' })
27}
28
29// Third-party integrity proof (no wallet required)
30const verify = await verifyPipelineByContractId(contractId)▋

Licensee escrow checkout

BSL licensees (Pemabu, sovereign vault) create escrow-backed checkout sessions via M2M ledger API key. See /licensee for SDK packages and deploy proof bundle links.

Licensee escrow create
1curl -X POST https://flomisma-platform-core.vercel.app/api/v1/licensee/escrow/create \
2  -H "x-ledger-api-key: your_ledger_key" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "tenantId": "tenant_licensee",
6    "templateId": "compliance-archive",
7    "escrowAmount": 49900,
8    "currency": "USD",
9    "buyerEmail": "buyer@example.com",
10    "metadata": { "source": "pemabu-marketplace" }
11  }'
12
13# Response
14# { "success": true, "data": { "checkoutSessionId": "...", "contractId": "..." } }▋

Enterprise vault (licensed)

Vault Engine deployment is available on enterprise and field-of-use licensed stacks — typically inside a regulated financial operator perimeter (e.g. Pemabu) or customer-controlled infrastructure. It is not offered as a public multi-tenant hosted custody API on flomisma.com. Contact sales or see Protocol Integrity for licensing.

Invoice generation

Generate a PDF invoice for a settlement event. Invoices can be downloaded for your records. Useful for providing receipts to counterparties.

curl
1# Generate a customer invoice PDF
2curl -X POST https://flomisma-platform-core.vercel.app/api/v1/ledger/invoices \
3  -H "x-ledger-api-key: your_key" \
4  -H "Content-Type: application/json" \
5  -d '{
6    "contractId": "LEDGER-ABCD1234",
7    "tenantId": "tenant_abc",
8    "tenantName": "Acme Corp",
9    "escrowAmount": 5000
10  }'
11
12# Response
13# { "success": true, "data": { "contractId": "LEDGER-ABCD1234", "sizeBytes": 42300 } }
14
15# Download invoice PDF
16curl -O https://flomisma-platform-core.vercel.app/api/v1/ledger/invoices/LEDGER-ABCD1234 \
17  -H "x-ledger-api-key: your_key"▋
View OpenAPI spec (Redoc) →
npm install @flomisma/api-types
Download YAML →

TypeScript types

types.ts
1import type { paths } from '@flomisma/api-types'
2
3type LedgerEntry =
4  paths['/ledger/entries']['post']['responses']['201']['content']['application/json']
5
6type SettlementPreview =
7  paths['/ledger/calculate-settlement']['post']['responses']['200']['content']['application/json']
8
9type Contract =
10  paths['/ledger/contracts']['post']['responses']['201']['content']['application/json']▋

No custody. No transmission.

The Settlement Ledger API is a software layer. Flomisma records ledger entries, computes settlement fees, tracks contract state, and generates invoices. Actual money movement happens through your own Stripe account, bank rails, or payment processor. You remain the regulated entity; Flomisma provides the infrastructure.