How do I submit a transaction to the JIL ledger?

Submit a POST request to /v1/ledger/transactions with the signed transaction payload. The ledger processes the transaction through compliance checks, consensus, and state application, returning a finality receipt within 2 seconds.

Can I query historical blocks?

Yes. Use GET /v1/ledger/blocks/{height} for specific blocks or GET /v1/ledger/blocks?from={height}&limit={count} for ranges. Each block includes the Merkle root, validator signatures, timestamp, and all included transactions.

Ledger API Specification - Transaction, Block & Account Endpoints

Overview

The JIL Sovereign Ledger API provides direct programmatic access to the settlement engine. All state reads, transaction submissions, compliance actions, and AMM operations route through the ledger-router at port 8000, which delegates to the Rust-based jil5600-core ledger engine. Transactions require WebAuthn (Passkey P-256) or Ed25519 signatures and are validated by a 14-of-20 validator quorum across 13 jurisdictions.

Base URLs

Environment	Base URL
Production	`https://ledger.jilsovereign.com`
Devnet	`https://devnet-ledger.jilsovereign.com`
Local (Docker)	`http://ledger-router:8000`

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-19T14:30:00.000Z`)
Amount Precision	Numeric (smallest unit) or string-encoded decimals
Auth Model	WebAuthn Passkey (P-256) or Ed25519 per-transaction signing

Devnet Access: Contact developers@jilsovereign.com to provision your devnet credentials and enable the development faucet endpoint before integrating.

Account State

GET /state/accounts/{id}

Get a specific account by ID with full details including authentication configuration, zone assignment, and account status.

Path Parameters

Parameter	Type	Required	Description
`id`	string	required	Account identifier (e.g. `"acc_abc123"`)

Response (200 OK)

{
  "account_id": "acc_abc123",
  "zone_id": "protected",
  "status": "active",
  "auth": {
    "type": "passkey_p256",
    "public_key_b64u": "base64url-encoded-public-key"
  },
  "nonce": 42,
  "created_at": "2026-01-15T10:00:00.000Z"
}
        

GET /state/accounts/{id}/balances

Get account balances for all assets held by the account.

Path Parameters

Parameter	Type	Required	Description
`id`	string	required	Account identifier

Response (200 OK)

[
  { "asset": "JIL", "amount": 1000.00 },
  { "asset": "USDC", "amount": 500.00 },
  { "asset": "jBTC", "amount": 0.25 }
]
        

GET /state/accounts/{id}/nonce

Get the current nonce for an account. The nonce must be included in every signed transaction to prevent replay attacks.

Path Parameters

Parameter	Type	Required	Description
`id`	string	required	Account identifier

Response (200 OK)

{
  "account_id": "acc_abc123",
  "nonce": 42
}
        

POST /accounts/register

Register a new account on the ledger with optional authentication configuration and zone assignment.

Request Body

Field	Type	Required	Description
`account_id`	string	required	Unique account identifier
`zone_id`	string	optional	Zone assignment (default: `"unprotected"`)
`auth`	AccountAuth	optional	Passkey P-256 or Ed25519 auth configuration

Response (200 OK)

{
  "ok": true,
  "account_id": "acc_abc123",
  "zone_id": "unprotected"
}
        

Transactions

POST /tx/payment

Submit a signed payment transaction. Requires a WebAuthn (Passkey P-256) or Ed25519 signature over the transaction payload. The ledger validates the signature, checks the nonce, enforces compliance policy, and applies the state transition atomically.

Request Body

Field	Type	Required	Description
`network_id`	string	required	Network identifier (e.g. `"devnet"`, `"jil-mainnet-1"`)
`from`	string	required	Sender account ID
`to`	string	required	Recipient account ID or @handle
`asset_id`	string	required	Asset symbol (e.g. `"JIL"`, `"USDC"`, `"jBTC"`)
`amount`	number	required	Amount in smallest unit
`nonce`	integer	required	Account nonce (must match current nonce from `/state/accounts/{id}/nonce`)
`auth`	TxAuth	required	Passkey or Ed25519 signature over the transaction payload
`memo`	string	optional	Transaction memo (max 256 characters)

Response (200 OK)

{
  "ok": true,
  "tx_id": "tx_abc123",
  "applied": true,
  "cosign_required": false,
  "policy_decision": "allow",
  "policy_reasons": []
}
        

Policy Enforcement: Every transaction passes through the on-chain policy registry. If cosign_required is true, the MPC co-signer must countersign before the transaction is finalized. The policy_reasons array describes any compliance flags triggered.

GET /tx/receipt/{id}

Get the transaction receipt for a completed transaction, including block height, hash, and gas consumed.

Path Parameters

Parameter	Type	Required	Description
`id`	string	required	Transaction ID (e.g. `"tx_abc123"`)

Response (200 OK)

{
  "tx_id": "tx_abc123",
  "status": "confirmed",
  "block_height": 1000042,
  "block_hash": "0x4e7f1a...c3d8b2",
  "timestamp": "2026-02-19T14:30:02.345Z",
  "gas_used": 21000
}
        

GET /tx/finality/{id}

Get the finality proof for a transaction with 14-of-20 validator quorum signatures, Merkle state root, and block hash. Used for independent proof verification.

Path Parameters

Parameter	Type	Required	Description
`id`	string	required	Transaction ID

Response (200 OK)

{
  "schema": "jil.tx_finality_receipt.v1",
  "tx_id": "tx_abc123",
  "finalized": true,
  "block_height": 1000042,
  "block_hash_b64u": "base64url-encoded-block-hash",
  "state_root_b64u": "base64url-encoded-state-root",
  "quorum_sig_b64u": "base64url-encoded-quorum-signature",
  "finalized_at": "2026-02-19T14:30:02.345Z"
}
        

Compliance Controls

Compliance endpoints enforce regulatory requirements at the ledger level. These operations require compliance authority credentials and are enforced across all 13 compliance zones. All compliance actions are immutably logged on-chain.

POST /account/freeze

Freeze an account, preventing all outbound transactions. Requires compliance authority. The account can still receive funds while frozen.

Request Body

Field	Type	Required	Description
`account_id`	string	required	Account to freeze
`reason`	string	required	Reason for freeze (e.g. `"sanctions_match"`, `"fraud_alert"`)
`evidence_id`	string	optional	Reference to supporting evidence record

Response (200 OK)

{
  "ok": true,
  "account_id": "acc_abc123",
  "status": "frozen",
  "frozen_at": "2026-02-19T14:30:00.000Z"
}
        

POST /account/unfreeze

Unfreeze an account, restoring normal transaction capabilities. Requires a valid appeal receipt or compliance authority approval.

Request Body

Field	Type	Required	Description
`account_id`	string	required	Account to unfreeze
`appeal_receipt_id`	string	required	Valid appeal receipt authorizing the unfreeze

Response (200 OK)

{
  "ok": true,
  "account_id": "acc_abc123",
  "status": "active",
  "unfrozen_at": "2026-02-19T15:00:00.000Z"
}
        

POST /account/containment/set

Set containment mode on an account. Restricts the account to lifeline transactions only - limited recipients and maximum amounts per transaction. Used for partial restrictions rather than full freeze.

Request Body

Field	Type	Required	Description
`account_id`	string	required	Account to contain
`reason`	string	required	Containment reason
`lifeline_allowlist`	string[]	optional	Allowed recipient addresses during containment
`lifeline_max_amount`	number	optional	Maximum amount per transaction during containment

Response (200 OK)

{
  "ok": true,
  "account_id": "acc_abc123",
  "status": "contained",
  "lifeline_allowlist": ["acc_essential_001"],
  "lifeline_max_amount": 500
}
        

POST /account/containment/release

Release an account from containment mode, restoring full transaction capabilities. Requires a containment release receipt from the compliance authority.

Request Body

Field	Type	Required	Description
`account_id`	string	required	Account to release from containment
`release_receipt_id`	string	required	Valid release receipt

Response (200 OK)

{
  "ok": true,
  "account_id": "acc_abc123",
  "status": "active",
  "released_at": "2026-02-19T16:00:00.000Z"
}
        

Compliance Authority Required: All freeze, unfreeze, containment, and release operations require compliance authority credentials. Unauthorized calls will receive a 401 UNAUTHORIZED response. All compliance actions are permanently recorded on-chain.

AMM v5

AMM v5 is the next-generation market making system with batch auctions, RFQ routing, and vault facility. The market operates across four states: NORMAL, ELEVATED, STRESSED, and HALTED, with automatic transitions based on volatility and liquidity metrics.

GET /amm/status

Get the current AMM market status including the active state, volatility metrics, and liquidity utilization.

Response (200 OK)

{
  "market_state": "NORMAL",  // NORMAL | ELEVATED | STRESSED | HALTED
  "state_entered_at": "2026-02-19T10:00:00.000Z",
  "volatility_bps": 150,
  "liquidity_utilization": "0.42"
}
        

GET /amm/state

Get the full AMM state with parameters for each market state level, including spread adjustments, batch size caps, and RFQ routing thresholds.

Response (200 OK)

{
  "current_state": "NORMAL",
  "states": {
    "NORMAL": { "spread_bps": 10, "batch_cap": 1000, "rfq_first": false },
    "ELEVATED": { "spread_bps": 25, "batch_cap": 500, "rfq_first": false },
    "STRESSED": { "spread_bps": 50, "batch_cap": 100, "rfq_first": true },
    "HALTED": { "spread_bps": 0, "batch_cap": 0, "rfq_first": false }
  }
}
        

POST /amm/preflight

Pre-flight check whether a transaction would be allowed under the current AMM state and entity risk profiles. Does not submit the transaction - use this to preview slippage and warnings before committing.

Request Body

Field	Type	Required	Description
`from_entity`	string	required	Sender entity ID
`to_entity`	string	required	Recipient entity ID
`amount`	string	required	Amount in decimal format (e.g. `"1000.00"`)
`pool_id`	string	optional	Specific liquidity pool ID to route through

Response (200 OK)

{
  "allowed": true,
  "estimated_slippage": "0.0015",
  "warnings": ["High volatility period"]
}
        

Governance

Governance endpoints control AMM market state transitions that require human authorization. All governance actions require multi-signature approval from authorized governance signers.

POST /amm/governance/halt

Emergency halt the AMM market. Transitions the market to HALTED state, stopping all new trades while allowing settlement of existing orders. Requires governance authority multi-sig.

Request Body

Field	Type	Required	Description
`signer`	string	required	Governance signer ID
`reason`	string	required	Halt reason (e.g. `"oracle_deviation"`, `"exploit_detected"`)

Response (200 OK)

{
  "ok": true,
  "market_state": "HALTED",
  "halted_at": "2026-02-19T14:30:00.000Z",
  "signer": "gov_signer_001",
  "reason": "oracle_deviation"
}
        

POST /amm/governance/resume

Resume AMM market from HALTED state. Transitions the market back to NORMAL with a gradual ramp-up. Requires governance authority multi-sig.

Request Body

Field	Type	Required	Description
`signer`	string	required	Governance signer ID

Response (200 OK)

{
  "ok": true,
  "market_state": "NORMAL",
  "resumed_at": "2026-02-19T16:00:00.000Z"
}
        

POST /amm/governance/propose

Propose a governance action for multi-sig approval. Supported actions include emergency_halt, resume_from_halt, and revoke_authority.

Request Body

Field	Type	Required	Description
`action`	string	required	Governance action (`"emergency_halt"`, `"resume_from_halt"`, `"revoke_authority"`)
`signer`	string	required	Proposer signer ID
`reason`	string	required	Reason for the proposal

Response (201 Created)

{
  "proposal_id": "prop_xyz789",
  "action": "emergency_halt",
  "status": "pending",
  "required_signatures": 3,
  "current_signatures": 1,
  "expires_at": "2026-02-20T14:30:00.000Z"
}
        

Development

POST /dev/faucet

Mint test tokens for development and testing. Only available when JIL_ENABLE_DEV_ENDPOINTS=1 is set on the ledger-router. Disabled by default in production and mainnet environments.

Request Body

Field	Type	Required	Description
`account_id`	string	required	Account to fund with test tokens
`amount`	number	required	Amount to mint
`asset_id`	string	optional	Asset to mint (default: `"JIL"`)

Response (200 OK)

{
  "ok": true,
  "account_id": "acc_abc123",
  "balance": 1000
}
        

Devnet Only: The faucet endpoint is disabled by default. Calling this endpoint on a production or mainnet environment will return 403 DEV_ENDPOINTS_DISABLED. Only enable JIL_ENABLE_DEV_ENDPOINTS=1 on devnet instances used for development and testing.

Error Codes

All error responses include a JSON body with error containing code, message, and optional details fields.

Error Response Format

{
  "error": {
    "code": "ACCOUNT_FROZEN",
    "message": "Account is frozen and cannot send transactions",
    "details": {
      "account_id": "acc_abc123",
      "frozen_at": "2026-02-19T14:30:00.000Z",
      "reason": "sanctions_match"
    }
  }
}
        

HTTP Status Codes

Status	Error Code	Description
`400`	`VALIDATION_ERROR`	Request body failed Zod schema validation. Check `details` for field-level errors.
`401`	`UNAUTHORIZED`	Missing or invalid authentication. Signature verification failed or compliance authority not recognized.
`403`	`DEV_ENDPOINTS_DISABLED`	Development endpoints are disabled. Set `JIL_ENABLE_DEV_ENDPOINTS=1` on devnet only.
`404`	`ACCOUNT_NOT_FOUND`	The specified account ID does not exist on the ledger.
`423`	`ACCOUNT_FROZEN`	Account is frozen. All outbound transactions are blocked until the account is unfrozen.
`429`	`RATE_LIMIT_EXCEEDED`	Too many requests. Response includes `retry_after_ms` field indicating when to retry.

How It Works

Tokenomics

Roadmap

Humanitarian Impact Fund

FAQ

Wallet

DEX

LaunchPad

Token Factory

Vaults

About

Contact

Overview

Base URLs

Protocol

Account State

GET /state/accounts/{id}

Path Parameters

Response (200 OK)

GET /state/accounts/{id}/balances

Path Parameters

Response (200 OK)

GET /state/accounts/{id}/nonce

Path Parameters

Response (200 OK)

POST /accounts/register

Request Body

Response (200 OK)

Transactions

POST /tx/payment

Request Body

Response (200 OK)

GET /tx/receipt/{id}

Path Parameters

Response (200 OK)

GET /tx/finality/{id}

Path Parameters

Response (200 OK)

Compliance Controls

POST /account/freeze

Request Body

Response (200 OK)

POST /account/unfreeze

Request Body

Response (200 OK)

POST /account/containment/set

Request Body

Response (200 OK)

POST /account/containment/release

Request Body

Response (200 OK)

AMM v5

GET /amm/status

Response (200 OK)

GET /amm/state

Response (200 OK)

POST /amm/preflight

Request Body

Response (200 OK)

Governance

POST /amm/governance/halt

Request Body

Response (200 OK)

POST /amm/governance/resume

Request Body

Response (200 OK)

POST /amm/governance/propose

Request Body

Response (201 Created)

Development

POST /dev/faucet

Request Body

Response (200 OK)

Error Codes

Error Response Format

HTTP Status Codes