How do I start building on JIL?

Install the JIL SDK for your language (Python, Node.js, or Go), obtain API credentials from jilsovereign.com/apply, and connect to the REST API or WebSocket endpoints. The SDK Guide provides complete code examples for common operations.

What APIs does JIL provide?

JIL provides 5 production APIs: Wallet API (port 8002) for MPC key management, Explorer API (port 8003) for blockchain queries, Launchpad API (port 8004) for token creation, Settlement API (port 8050) for cross-border payments, and Ledger API (port 8000) for transaction submission.

Does JIL support WebSocket streaming?

Yes. JIL provides WebSocket endpoints for real-time block updates, settlement status changes, DEX price feeds, and validator health metrics. WebSocket connections support automatic reconnection and subscription filtering.

What authentication does the API use?

JIL APIs use JWT bearer tokens for authentication. API keys are generated through the developer portal, and tokens are issued via the /auth/token endpoint with configurable expiration and scope restrictions.

Developer SDK Guide - Build on JIL Sovereign | APIs, Libraries & Quickstart

Quick Start

Get up and running with the JIL API in under 5 minutes.

Base URLs

Environment	Base URL
Production	`https://api.jilsovereign.com`
Devnet	`https://devnet-api.jilsovereign.com`
Local (Docker)	`http://wallet-api:8002`

Your First API Call

// Check API health
const response = await fetch('https://api.jilsovereign.com/health');
const data = await response.json();

console.log(data);
// { ok: true, service: 'wallet-api', ts: '2026-02-02T...' }
        

Create a Wallet & Send Payment

// 1. Register a new user
const register = await fetch('/auth/register', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'SecurePass123!'
  })
});
const { token, accountId } = await register.json();

// 2. Get payment options (includes passkey challenge)
const options = await fetch('/wallet/send/options', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    to: '@alice.jil',  // or wallet address
    asset: 'JIL',
    amount: '100.00'
  })
});

// 3. Sign with WebAuthn and submit
const { challenge, txIntent } = await options.json();
const credential = await navigator.credentials.get({ publicKey: challenge });

const result = await fetch('/wallet/send/submit', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ txIntent, credential })
});

const { txId, receipt } = await result.json();
console.log('Transaction ID:', txId);
        

Authentication

JIL supports multiple authentication methods for different use cases.

Authentication Methods

Method	Use Case	Security Level
JWT Bearer Token	API access after login	Standard
WebAuthn/Passkeys	Transaction signing	High (phishing-resistant)
OAuth 2.0	Social login (Google, Apple)	Standard
API Keys	Server-to-server (Settlement API)	High

JWT Authentication

// Login to get JWT token
const login = await fetch('/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'SecurePass123!'
  })
});

const { token } = await login.json();

// Use token in subsequent requests
const balances = await fetch('/wallet/balances', {
  headers: { 'Authorization': `Bearer ${token}` }
});
        

WebAuthn/Passkey Registration

// 1. Get registration options from server
const optionsRes = await fetch('/auth/passkey/register/options', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  }
});
const options = await optionsRes.json();

// 2. Create credential using WebAuthn API
const credential = await navigator.credentials.create({
  publicKey: options.publicKey
});

// 3. Send credential to server for verification
await fetch('/auth/passkey/register/verify', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    id: credential.id,
    rawId: bufferToBase64(credential.rawId),
    response: {
      clientDataJSON: bufferToBase64(credential.response.clientDataJSON),
      attestationObject: bufferToBase64(credential.response.attestationObject)
    }
  })
});
        

Passkeys are required for Protected and Premium zone transactions. They provide phishing-resistant authentication bound to the user's device.

Wallet API

The Wallet API handles user accounts, balances, payments, and recovery ceremonies.

Endpoints

Method	Endpoint	Description
POST	`/auth/register`	Register new user
POST	`/auth/login`	Login with email/password
GET	`/wallet/balances`	Get account balances
POST	`/wallet/send/options`	Get payment options with challenge
POST	`/wallet/send/submit`	Submit signed payment
GET	`/api/proof/tx/:txId`	Get transaction proof receipt
GET	`/handle/resolve/:handle`	Resolve @handle to address
POST	`/handle/register`	Register @username.jil handle

Get Balances

const response = await fetch('/wallet/balances', {
  headers: { 'Authorization': `Bearer ${token}` }
});

const balances = await response.json();
// {
//   accountId: "acc_123...",
//   zone: "protected",
//   assets: [
//     { symbol: "JIL", balance: "1000.00", usdValue: "2500.00" },
//     { symbol: "USDC", balance: "500.00", usdValue: "500.00" }
//   ]
// }
        

Handle Resolution

// Resolve @alice.jil to wallet address
const response = await fetch('/handle/resolve/alice.jil');
const { address, profile } = await response.json();
// { address: "jil1abc123...", profile: { avatar: "...", displayName: "Alice" } }
        

Recovery Ceremony

If a user loses access, guardians can help recover their account:

// 1. Start recovery ceremony
const start = await fetch('/wallet/recovery/start', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    accountId: 'acc_123...',
    newCredentialCommitment: '0x...'  // Hash of new passkey
  })
});
const { ceremonyId } = await start.json();

// 2. Guardians approve (2-of-3 required)
await fetch('/wallet/recovery/approve', {
  method: 'POST',
  body: JSON.stringify({
    ceremonyId,
    guardianSignature: '...'  // Ed25519 signature
  })
});

// 3. After 24h timelock, finalize
await fetch('/wallet/recovery/finalize', {
  method: 'POST',
  body: JSON.stringify({ ceremonyId })
});
        

Ledger API (L1)

Direct access to the JIL-5600 ledger for account state and transaction submission.

Base URL

Environment	URL	Port
Production	`https://ledger.jilsovereign.com`	8081
Local (Docker)	`http://ledger-service:8081`	8081

Endpoints

Method	Endpoint	Description
GET	`/state/accounts/:id`	Get account state
GET	`/state/accounts/:id/balances`	Get account balances
GET	`/state/accounts/:id/nonce`	Get account nonce
POST	`/tx/payment`	Submit payment transaction
GET	`/tx/receipt/:id`	Get transaction receipt
GET	`/amm/status`	Get AMM market status
POST	`/amm/preflight`	Preflight order check

Get Account State

const response = await fetch('https://jilsovereign.com/api/ledger/state/accounts/acc_123');
const account = await response.json();
// {
//   id: "acc_123",
//   zone: "protected",
//   credentialCommitment: "0x...",
//   frozen: false,
//   containment: false,
//   guardians: ["guardian1", "guardian2", "guardian3"],
//   nonce: 42
// }
        

AMM Preflight Check

// Check if order would be accepted before submitting
const preflight = await fetch('/amm/preflight', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    entityId: 'acc_123',
    orderType: 'market',
    side: 'buy',
    baseAsset: 'JIL',
    quoteAsset: 'USDC',
    amount: '1000'
  })
});

const result = await preflight.json();
// {
//   allowed: true,
//   estimatedPrice: "2.50",
//   estimatedSlippage: "0.1%",
//   complianceStatus: "passed",
//   riskFlags: []
// }
        

Launchpad API

Create and participate in Liquidity Bootstrapping Pool (LBP) auctions.

Endpoints

Method	Endpoint	Description
GET	`/v1/lbp/auctions`	List all auctions
POST	`/v1/lbp/auctions`	Create new auction
POST	`/v1/lbp/auctions/:id/bid`	Place bid
POST	`/v1/lbp/auctions/:id/close`	Close auction
GET	`/v1/lbp/auctions/:id/receipt`	Get auction receipt

Create LBP Auction

const auction = await fetch('/v1/lbp/auctions', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: 'My Token Launch',
    tokenSymbol: 'MTK',
    totalSupply: '1000000',
    startPrice: '10.00',
    endPrice: '1.00',
    duration: 86400,  // 24 hours in seconds
    vestingPeriod: 2592000  // 30 days
  })
});

const { auctionId } = await auction.json();
        

Place Bid

const bid = await fetch(`/v1/lbp/auctions/${auctionId}/bid`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    bidder: 'acc_123',
    amount: '1000',  // USDC amount
    maxPrice: '5.00'   // Max price willing to pay
  })
});
        

Settlement API (B2B)

The Institutional Settlement API enables banks, payment processors, and financial institutions to submit, track, and reconcile settlements on the JIL settlement protocol. This is a server-to-server API with API key authentication, not consumer-facing.

Base URL: https://api.jilsovereign.com/v1 (Production) | https://api-sandbox.jilsovereign.com/v1 (Sandbox)
Port: 8110 | Auth: API Key + optional HMAC signing
Full Reference: Settlement API Specification

Authentication

All requests require an x-api-key header. For production environments, HMAC request signing is also required for tamper-proof request verification.

// Required header
x-api-key: sk_live_your_api_key_here

// Optional HMAC signing (required when REQUIRE_HMAC=true)
x-timestamp: 1739097600
x-signature: sha256=HMAC-SHA256(secret, method + path + timestamp + sha256(body))
        

Client Tiers

Tier	Rate Limit	Batch Size	Use Case
Standard	60 req/min	Up to 25	Small institutions, testing
Premium	300 req/min	Up to 50	Mid-size banks, payment processors
Enterprise	6,000 req/min	Up to 100	Large banks, high-volume settlement

Endpoints Overview

Method	Endpoint	Description
POST	`/v1/settlements`	Submit a single settlement
POST	`/v1/settlements/batch`	Submit batch of 1-100 settlements
GET	`/v1/settlements/:id`	Get settlement status and details
GET	`/v1/settlements/:id/proof`	Get cryptographic finality proof
GET	`/v1/settlements/batch/:batch_id`	Get batch summary
GET	`/v1/reconciliation/transactions`	Query settlements with filters
POST	`/v1/webhooks`	Create webhook subscription
GET	`/v1/webhooks`	List webhook subscriptions
DELETE	`/v1/webhooks/:id`	Remove webhook subscription

Submit a Settlement

const response = await fetch('https://api.jilsovereign.com/v1/settlements', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'sk_live_your_api_key_here'
  },
  body: JSON.stringify({
    external_id: 'TXN-2026-0209-001',
    from_account: 'jil1bankA_treasury',
    to_account: 'jil1bankB_operations',
    asset: 'JIL',
    amount: '250000.00',
    zone_id: 'zone-us-east',
    memo: 'Cross-border settlement Q1-2026'
  })
});

// Response: 201 Created
{
  "id": "stl_a1b2c3d4e5f6",
  "status": "received",
  "external_id": "TXN-2026-0209-001",
  "created_at": "2026-02-09T14:30:00.000Z"
}
        

Check Settlement Status

const status = await fetch(
  'https://api.jilsovereign.com/v1/settlements/stl_a1b2c3d4e5f6',
  { headers: { 'x-api-key': 'sk_live_your_api_key_here' } }
);

// Response shows full lifecycle
{
  "id": "stl_a1b2c3d4e5f6",
  "status": "final",
  "from_account": "jil1bankA_treasury",
  "to_account": "jil1bankB_operations",
  "asset": "JIL",
  "amount": "250000.00",
  "l1_tx_id": "0xabc123...",
  "l1_block_height": 1847293,
  "confirmations": 6,
  "finalized_at": "2026-02-09T14:30:09.000Z"
}
        

Settlement Lifecycle

Every settlement progresses through a defined state machine. The typical flow for a successful settlement takes approximately 9 seconds (6 block confirmations at 1.5s each).

State	Description	Next States
`received`	Settlement accepted, queued for compliance	compliance_check
`compliance_check`	ZK compliance verification in progress	submitted, rejected
`submitted`	Transaction submitted to settlement ledger	confirmed, failed
`confirmed`	Included in a block, accumulating confirmations	final, failed
`final`	6+ confirmations, cryptographic finality achieved	(terminal)
`rejected`	Compliance check denied the transaction	(terminal)
`failed`	L1 error or timeout (60s)	(terminal)

Webhook Events

Subscribe to real-time settlement lifecycle events via webhooks. All webhook payloads are signed with HMAC-SHA256 for verification.

// Create a webhook subscription
const webhook = await fetch('https://api.jilsovereign.com/v1/webhooks', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'sk_live_your_api_key_here'
  },
  body: JSON.stringify({
    url: 'https://your-bank.com/webhooks/jil-settlement',
    events: ['SETTLEMENT_FINAL', 'SETTLEMENT_FAILED', 'SETTLEMENT_REJECTED']
  })
});

// Response includes the signing secret (shown only once)
{
  "id": "wh_x1y2z3",
  "secret": "whsec_abc123...",
  "events": ["SETTLEMENT_FINAL", "SETTLEMENT_FAILED", "SETTLEMENT_REJECTED"]
}
        

Reconciliation

Query historical settlements with filters for reconciliation and reporting. Supports cursor-based pagination for large result sets.

// Query settlements with filters
const report = await fetch(
  'https://api.jilsovereign.com/v1/reconciliation/transactions?' +
  new URLSearchParams({
    status: 'final',
    asset: 'JIL',
    from_date: '2026-02-01',
    to_date: '2026-02-09',
    limit: '50'
  }),
  { headers: { 'x-api-key': 'sk_live_your_api_key_here' } }
);

// Response includes summary and paginated results
{
  "settlements": [...],
  "summary": {
    "total_count": 1847,
    "total_amount": "45230000.00",
    "by_status": { "final": 1847 }
  },
  "next_cursor": "eyJpZCI6InN0bF8..."
}
        

Full API Reference: For complete endpoint documentation including request/response schemas, error codes, HMAC signing details, and batch processing, see the Institutional Settlement API Specification.

Explorer API

Query blockchain data for block explorers and analytics.

Coming Soon: The Explorer API is currently in development. Basic health endpoints are available.

Planned Endpoints

Method	Endpoint	Description
GET	`/blocks`	List recent blocks
GET	`/blocks/:height`	Get block by height
GET	`/transactions`	List recent transactions
GET	`/transactions/:hash`	Get transaction details
GET	`/accounts/:address`	Get account details
GET	`/validators`	List validators

SDKs & Libraries

Official SDKs

Language	Package	Status
JavaScript/TypeScript	`@jil-sovereign/sdk`	Available
Python	`jil-sovereign-sdk`	Coming Soon
Rust	`jil-sovereign-rs`	Coming Soon
Go	`jil-sovereign-go`	Coming Soon

JavaScript SDK Installation

npm install @jil-sovereign/sdk
# or
yarn add @jil-sovereign/sdk
        

SDK Usage

import { JILClient } from '@jil-sovereign/sdk';

// Initialize client
const client = new JILClient({
  baseUrl: 'https://api.jilsovereign.com',
  network: 'mainnet'  // or 'devnet'
});

// Authenticate
await client.login('user@example.com', 'password');

// Get balances
const balances = await client.wallet.getBalances();

// Send payment
const tx = await client.wallet.send({
  to: '@alice.jil',
  asset: 'JIL',
  amount: '100'
});

// Wait for confirmation
const receipt = await client.waitForReceipt(tx.id);
console.log('Confirmed in block:', receipt.blockHeight);
        

Error Handling

Error Response Format

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Account has insufficient balance for this transaction",
    "details": {
      "required": "100.00",
      "available": "50.00",
      "asset": "JIL"
    }
  }
}
        

Common Error Codes

Code	HTTP Status	Description
`UNAUTHORIZED`	401	Missing or invalid authentication
`FORBIDDEN`	403	Insufficient permissions
`NOT_FOUND`	404	Resource not found
`INSUFFICIENT_BALANCE`	400	Not enough funds
`ACCOUNT_FROZEN`	403	Account is frozen
`PASSKEY_REQUIRED`	403	Transaction requires passkey signature
`COMPLIANCE_FAILED`	403	KYC/AML check failed
`RATE_LIMITED`	429	Too many requests

Rate Limits

Tier	Requests/min	Burst
Anonymous	60	10
Authenticated	300	50
Enterprise	6,000	500

Rate Limit Headers

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 295
X-RateLimit-Reset: 1706889600
        

Need higher limits? Contact us at contact@jilsovereign.com for enterprise access.

REST Endpoints

50+

WebSocket Streams

Languages

Auth

JWT + API Key

Version: 1.0 - February 2026
Entity: JIL Sovereign Technologies, Inc.
Support: developers@jilsovereign.com
Enterprise: contact@jilsovereign.com

Overview

How It Works

Beneficiary Identity

Policy Corridors

Deterministic Finality

Architecture

Security Model

Governance

Integration

Corridors Overview

Institutional Overview

Pricing

All Scenarios

Humanitarian Impact Fund

Technical Assurance

Verify Receipt

Receipt Example

Documentation

APIs & Bridges

Architecture Docs

Glossary

BID API

About

Team

Partners

Roadmap

Investors

Contact

Blog

All Documentation

Quick Start

Base URLs

Your First API Call

Create a Wallet & Send Payment

Authentication

Authentication Methods

JWT Authentication

WebAuthn/Passkey Registration

Wallet API

Endpoints

Get Balances

Handle Resolution

Recovery Ceremony

Ledger API (L1)

Base URL

Endpoints

Get Account State

AMM Preflight Check

Launchpad API

Endpoints

Create LBP Auction

Place Bid

Settlement API (B2B)

Authentication

Client Tiers

Endpoints Overview

Submit a Settlement

Check Settlement Status

Settlement Lifecycle

Webhook Events

Reconciliation

Explorer API

Planned Endpoints

SDKs & Libraries

Official SDKs

JavaScript SDK Installation

SDK Usage

Error Handling

Error Response Format

Common Error Codes

Rate Limits

Rate Limit Headers