Overview
The JIL Sovereign Institutional Settlement API provides programmatic access to the settlement engine for banks, payment processors, custodians, and other financial institutions. All settlements are processed through the JIL Sovereign L1 ledger with compliance checks, cryptographic finality proofs, and full audit trails.
Base URLs
| Environment | Base URL |
|---|---|
| Production | https://settlement.jilsovereign.com |
| Devnet | https://devnet-settlement.jilsovereign.com |
| Local (Docker) | http://settlement-api:8050 |
Protocol
| Property | Value |
|---|---|
| Transport | HTTPS (TLS 1.3 required in production) |
| Content Type | application/json |
| Character Encoding | UTF-8 |
| Date Format | ISO 8601 (2026-02-09T14:30:00.000Z) |
| Amount Precision | String-encoded decimals (e.g. "1500.00") |
| Idempotency | By (client_id, external_id) pair |
Authentication
All API requests must include a valid API key. Enterprise clients may additionally enable HMAC request signing for enhanced security.
API Key Authentication
Include your API key in the x-api-key header with every request.
HMAC Request Signing (Optional)
For enhanced security, enterprise clients can enable HMAC-SHA256 request signing. When enabled, every request
must include two additional headers: x-timestamp and x-signature.
Signature Formula
Signed Request Headers
x-timestamp must be within 5 minutes of server time.
Requests with stale timestamps are rejected with HTTP 401.
Rate Limit Tiers
| Tier | Requests/min | Provisioning |
|---|---|---|
| Standard | 60 | Default for all API keys |
| Premium | 300 | Available on request |
| Enterprise | 6,000 | Dedicated onboarding required |
Settlement Submission
POST /v1/settlements
Submit a single settlement for processing. The settlement is validated, checked for compliance, and submitted to the L1 ledger. Idempotent by (client_id, external_id).
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
external_id | string | required | Your unique identifier for this settlement (max 128 chars) |
settlement_type | string | optional | Settlement type: SIMPLE, DVP, or PVP. Defaults to SIMPLE. |
lane | string | optional | Settlement lane: FI_TO_FI, FI_TO_CRYPTO, or CRYPTO_TO_CRYPTO. Auto-detected from account types if omitted. |
from_account | string | required | Source account address or JIL handle |
to_account | string | required | Destination account address or JIL handle |
asset | string | required | Asset symbol (e.g. JIL, USDC, BTC) |
amount | string | required | Amount as decimal string (e.g. "1500.00") |
zone_id | string | optional | Target settlement zone. Defaults to auto-routing. |
memo | string | optional | Arbitrary memo field (max 256 chars) |
SIMPLE is a single-leg transfer. DVP (Delivery vs Payment) links an asset leg with a payment leg - both commit atomically or neither does. PVP (Payment vs Payment) links two payment legs for FX settlement. DVP/PVP settlements require both legs to attest readiness before finalization.
Example Request
Response (201 Created)
POST /v1/settlements/batch
Submit a batch of 1 to 100 settlements in a single request. Each settlement is independently validated and processed.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
external_batch_id | string | required | Your unique identifier for this batch (max 128 chars) |
settlements | array | required | Array of settlement objects (1-100 items) |
Example Request
Response (201 Created)
Settlement Actions
POST /v1/settlements/:id/cancel
Cancel a settlement that has not yet reached submitted state. Settlements in received, validated, compliance_check, accepted, or ready states can be cancelled. Returns HTTP 409 if the settlement has already been submitted to the L1 ledger.
Response (200 OK)
POST /v1/settlements/:id/attest-ready
Attest that your side of a DVP or PVP settlement is ready for finalization. Both parties must attest readiness before the settlement can proceed to submitted state. Only applicable to DVP/PVP settlement types. Returns HTTP 409 if the settlement is not in accepted state or is a SIMPLE type.
Response (200 OK)
Settlement Status
GET /v1/settlements/:id
Retrieve the full status of a settlement including L1 ledger details, compliance results, and timing information.
Response (200 OK)
GET /v1/settlements/:id/proof
Retrieve the cryptographic finality proof for a completed settlement. Only available when the settlement
status is final. Returns HTTP 409 if the settlement has not yet reached finality.
Response (200 OK)
GET /v1/settlements/:id/receipt
Retrieve the full settlement receipt including fee breakdown, compliance attestation, and reconciliation data. Only available when the settlement status is final.
Response (200 OK)
settlement_receipt includes beneficiary_binding_hash, beneficiary_verified_at, and bec_check_result.
GET /v1/settlements/batch/:batch_id
Retrieve the summary and individual results for a batch settlement.
Response (200 OK)
Settlement Lifecycle
Every settlement follows a deterministic state machine from submission through finality. The lifecycle ensures compliance validation, L1 ledger confirmation, and cryptographic proof generation.
State Machine (9 States)
State Descriptions
| State | Description | Terminal? |
|---|---|---|
received | Settlement accepted by the API and queued for structural validation. | No |
validated | Structural validation passed (fields, formats, accounts). Queued for compliance. | No |
compliance_check | Compliance validation in progress (sanctions, AML, jurisdiction, travel rule evaluation). | No |
accepted | Compliance passed. Awaiting readiness attestation (for DVP/PVP) or auto-promoted to ready (for SIMPLE). | No |
ready | All parties have attested readiness. Queued for L1 ledger submission. | No |
submitted | Submitted to the L1 ledger for inclusion in a block. | No |
confirmed | Included in a block. Awaiting finality (6 confirmations, ~9 seconds at 1.5s block time). | No |
final | Settlement is complete with a cryptographic finality proof. Fees calculated at this state. Irreversible. | Yes |
rejected | Compliance denied the settlement. Review compliance receipt for details. | Yes |
failed | L1 ledger error or timeout. Can be resubmitted with same external_id. | Yes |
cancelled | Cancelled by the submitting party before reaching submitted state. | Yes |
expired | Time-to-live (TTL) exceeded without reaching a terminal state. | Yes |
final status within
10-15 seconds. Compliance checks complete in under 500ms. The L1 ledger confirms in 1.5-second blocks with finality after 6 confirmations (~9 seconds).
Settlement Types
| Type | Legs | Readiness | Use Case |
|---|---|---|---|
SIMPLE | Single leg (one-way transfer) | Auto-promoted from accepted to ready | Standard transfers, payroll, distributions |
DVP | Asset leg + Payment leg | Both parties must call /attest-ready. Per-leg compliance applied. | Securities settlement, tokenized asset trades |
PVP | Payment A + Payment B | Both parties must call /attest-ready. Per-leg compliance applied. | FX settlement, cross-currency swaps |
Settlement Lanes
Every settlement is routed through one of three lanes. The lane determines compliance depth, fee tier, and reconciliation format.
| Lane | Description | Compliance | Typical Fee |
|---|---|---|---|
FI_TO_FI | Financial Institution to Financial Institution. Full regulatory compliance corridor between LEI-identified participants. | Sanctions, AML, jurisdiction, travel rule evaluation, cross-border checks | 3-4 bps |
FI_TO_CRYPTO | Financial Institution to crypto-native account. Bridge between regulated and on-chain ecosystems. | Sanctions, AML, jurisdiction, travel rule evaluation, address screening | 4-5 bps |
CRYPTO_TO_CRYPTO | On-chain account to on-chain account. Permissionless settlement with baseline compliance. | Sanctions screening, address risk scoring | 3-5 bps |
final state, not at submission. The fee is based on the settlement notional at the time of finality. Settlements that do not reach finality incur no fee.
Reconciliation
GET /v1/reconciliation/transactions
Query settlement transactions for reconciliation. Supports cursor-based pagination, date ranges, and filtering by status, asset, and account.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
cursor | string | optional | Cursor for pagination. Omit for first page. |
limit | integer | optional | Results per page, 1-200. Default: 50. |
status | string | optional | Filter by status (e.g. final, failed). |
asset | string | optional | Filter by asset symbol (e.g. USDC). |
account | string | optional | Filter by from or to account address. |
from_date | string | optional | Start date (ISO 8601). Inclusive. |
to_date | string | optional | End date (ISO 8601). Exclusive. |
Response (200 OK)
cursor value from the response to fetch the next page.
When has_more is false, you have reached the end of the result set.
Webhooks
Subscribe to real-time settlement events via webhooks. All webhook payloads are signed with HMAC-SHA256 so you can verify authenticity before processing.
Webhook Events
| Event | Description |
|---|---|
SETTLEMENT_RECEIVED | Settlement accepted and queued for validation |
SETTLEMENT_VALIDATED | Structural validation passed, queued for compliance |
SETTLEMENT_COMPLIANCE_CHECK | Compliance validation started (sanctions, AML, jurisdiction, travel rule) |
SETTLEMENT_ACCEPTED | Compliance passed, awaiting readiness attestation |
SETTLEMENT_READY | All parties attested readiness, queued for L1 submission |
SETTLEMENT_REJECTED | Compliance denied the settlement |
SETTLEMENT_SUBMITTED | Submitted to L1 ledger |
SETTLEMENT_CONFIRMED | Included in a block, awaiting finality |
SETTLEMENT_FINAL | Settlement finalized with cryptographic proof. Fee calculated. |
SETTLEMENT_FAILED | L1 error or timeout |
SETTLEMENT_CANCELLED | Settlement cancelled before L1 submission |
SETTLEMENT_EXPIRED | Settlement TTL exceeded |
BATCH_CREATED | Batch accepted for processing |
BATCH_COMPLETED | All settlements in batch reached terminal state |
Managing Webhooks
POST /v1/webhooks
Create a webhook subscription. The signing secret is returned only once in the creation response.
GET /v1/webhooks
List all webhook subscriptions for your API key.
DELETE /v1/webhooks/:id
Deactivate a webhook subscription. Deactivated webhooks stop receiving events immediately.
Webhook Payload Format
Signature Verification
Retry Policy
Failed webhook deliveries (non-2xx response or timeout after 10 seconds) are retried with exponential backoff. After 8 failed attempts, the delivery is marked as permanently failed.
| Attempt | Delay | Cumulative Wait |
|---|---|---|
| 1 (initial) | Immediate | 0s |
| 2 | 30 seconds | 30s |
| 3 | 2 minutes | 2m 30s |
| 4 | 10 minutes | 12m 30s |
| 5 | 30 minutes | 42m 30s |
| 6 | 1 hour | 1h 42m 30s |
| 7 | 2 hours | 3h 42m 30s |
| 8 | 4 hours | 7h 42m 30s |
Health Check
GET /health
Returns the health status of the settlement API including connectivity to downstream dependencies. This endpoint does not require authentication.
Response (200 OK)
Code Examples
Complete JavaScript/TypeScript examples for common settlement operations.
1. API Client Setup
2. Submit a Settlement
3. Poll for Finality
4. Batch Settlement
5. Reconciliation Query
Error Codes
All error responses include a JSON body with error, message, and optional details fields.
Error Response Format
HTTP Status Codes
| Status | Error Code | Description |
|---|---|---|
400 | VALIDATION_ERROR | Request body failed Zod schema validation. |
401 | UNAUTHORIZED | Missing or invalid API key, expired HMAC timestamp, or invalid signature. |
403 | ZONE_NOT_ALLOWED | API key not authorized for the requested settlement zone. |
404 | SETTLEMENT_NOT_FOUND | Settlement ID does not exist or does not belong to your client. |
404 | BATCH_NOT_FOUND | Batch ID does not exist or does not belong to your client. |
404 | WEBHOOK_NOT_FOUND | Webhook ID does not exist or does not belong to your client. |
409 | NOT_YET_FINALIZED | Finality proof requested for non-final settlement. |
429 | RATE_LIMIT_EXCEEDED | Too many requests. Includes retry_after_ms. |
Rate Limits
Rate limits are enforced per API key using a sliding window algorithm. Rate limit information is returned in response headers for every request.
Rate Limit Tiers
| Tier | Requests/min | Batch Size | Concurrent Batches |
|---|---|---|---|
| Standard | 60 | Up to 25 | 1 |
| Premium | 300 | Up to 50 | 5 |
| Enterprise | 6,000 | Up to 100 | Unlimited |
Rate Limit Headers
Every response includes the following rate limit headers.
| Header | Description |
|---|---|
x-ratelimit-limit | Maximum requests allowed in the current window |
x-ratelimit-remaining | Requests remaining in the current window |
x-ratelimit-reset | Unix timestamp (seconds) when the rate limit window resets |