How do I launch a token on JIL?

Use POST /v1/launchpad/pools to create a Liquidity Bootstrapping Pool (LBP). Configure the token pair, initial weights, duration, and starting price. The LBP automatically adjusts weights over time for fair price discovery.

What is a Liquidity Bootstrapping Pool?

An LBP is a dynamic auction mechanism where token weights shift over time from high (e.g., 90/10) to balanced (50/50). This creates natural price discovery as early buyers pay a premium that decreases over the auction duration, preventing bot front-running.

Launchpad API Specification - LBP Auctions, Token Launches & Journal Receipts

Overview

The JIL Sovereign Launchpad API provides programmatic access to Liquidity Bootstrapping Pool (LBP) auction infrastructure. Project teams can create time-weighted descending-price auctions for fair token distribution, while participants place bids that are recorded with cryptographic signatures and full journal event histories. Every auction action produces a signed evidence capsule for transparent, auditable token launches.

Base URLs

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

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`)
Authentication	`x-api-key` header (required for write operations)

LBP Mechanics: Liquidity Bootstrapping Pools use a time-weighted descending price curve. The auction starts at a high price and decreases over time, encouraging fair price discovery. Bidders are incentivized to wait for a fair price rather than front-running. All events are cryptographically signed with HMAC and include SHA-256 content hashes for tamper-proof audit trails.

GET /health

Health check endpoint. Returns service status and uptime information.

Response (200 OK)

{
  "status": "healthy",
  "service": "launchpad-api",
  "version": "1.0.0",
  "uptime": 86400
}
        

GET /metrics

Prometheus metrics endpoint for monitoring. Returns auction counts, bid volumes, and latency histograms.

Auction Management

GET /v1/lbp/auctions

List all auctions. Returns up to 200 auctions sorted by creation date descending.

Response (200 OK)

{
  "ok": true,
  "auctions": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "pair": "JIL/USDC",
      "start_price": 0.09,
      "end_price": 0.15,
      "duration_seconds": 3600,
      "liquidity_usd": 200000,
      "status": "active",
      "created_at": "2026-02-19T10:00:00.000Z",
      "bids": []
    }
  ]
}
        

POST /v1/lbp/auctions

Create a new LBP auction. All parameters have sensible defaults. A journal event of type LBP_AUCTION_CREATED is generated with a cryptographic signature.

Request Body

Parameter	Type	Default	Description
`pair`	string	optional `JIL/USDC`	Trading pair for the auction
`start_price`	number	optional `0.09`	Starting price in quote currency
`end_price`	number	optional `0.15`	Target end price in quote currency
`duration_seconds`	integer	optional `3600`	Auction duration in seconds
`liquidity_usd`	number	optional `200000`	Total liquidity pool size in USD

Response (201 Created)

{
  "ok": true,
  "auction": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "pair": "JIL/USDC",
    "start_price": 0.09,
    "end_price": 0.15,
    "duration_seconds": 3600,
    "liquidity_usd": 200000,
    "status": "active",
    "created_at": "2026-02-19T10:00:00.000Z",
    "bids": []
  },
  "journal_event": {
    "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "type": "LBP_AUCTION_CREATED",
    "hash_b64u": "dGhpcyBpcyBhIFNIQTI1NiBjb250ZW50IGhhc2g",
    "sig_b64u": "SElNQUMgc2lnbmF0dXJlIG9mIGV2ZW50"
  }
}
        

POST /v1/lbp/auctions/{id}/close

Close an active auction. Creates a journal event of type LBP_AUCTION_CLOSED and updates the auction status to "closed".

Path Parameters

Parameter	Type	Required	Description
`id`	string (UUID)	required	Auction ID

Response (200 OK)

{
  "ok": true,
  "auction": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "closed",
    "closed_at": "2026-02-19T11:00:00.000Z"
  },
  "journal_event": {
    "event_id": "f0e1d2c3-b4a5-6789-0abc-def123456789",
    "type": "LBP_AUCTION_CLOSED",
    "hash_b64u": "Y2xvc2UgZXZlbnQgU0hBMjU2IGhhc2g",
    "sig_b64u": "SElNQUMgY2xvc2Ugc2lnbmF0dXJl"
  }
}
        

Bidding

POST /v1/lbp/auctions/{id}/bid

Place a bid on an active auction. Bids are recorded with cryptographic signatures and generate a journal event of type LBP_BID_PLACED.

Path Parameters

Parameter	Type	Required	Description
`id`	string (UUID)	required	Auction ID

Request Body

Field	Type	Required	Description
`wallet`	string	optional	Wallet address of the bidder (default: `"demo_wallet"`)
`amount_usdc`	number	required	Bid amount in USDC (must be greater than 0)

Response (200 OK)

{
  "ok": true,
  "bid": {
    "bid_id": "b1d2e3f4-a5b6-7890-cdef-123456789abc",
    "wallet": "0x9F1caCaC025C42bb4Cc854cefC5fE784D3A10a1C",
    "amount_usdc": 1000,
    "created_at": "2026-02-19T10:30:00.000Z"
  },
  "journal_event": {
    "event_id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
    "type": "LBP_BID_PLACED",
    "hash_b64u": "YmlkIGV2ZW50IFNIQTIg1NiBjb250ZW50",
    "sig_b64u": "SElNQUMgYmlkIHNpZ25hdHVyZQ"
  }
}
        

Journal & Receipts

GET /v1/lbp/auctions/{id}/journal

Get the complete event history for an auction. Returns up to 500 events, each with cryptographic hashes and HMAC signatures for tamper-proof auditability.

Path Parameters

Parameter	Type	Required	Description
`id`	string (UUID)	required	Auction ID

Response (200 OK)

{
  "ok": true,
  "auction_id": "550e8400-e29b-41d4-a716-446655440000",
  "events": [
    {
      "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "type": "LBP_AUCTION_CREATED",
      "created_at": "2026-02-19T10:00:00.000Z",
      "data": {
        "pair": "JIL/USDC",
        "start_price": 0.09,
        "end_price": 0.15
      },
      "hash_b64u": "base64url-encoded-SHA256-hash",
      "sig_b64u": "base64url-encoded-HMAC-signature"
    },
    {
      "event_id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
      "type": "LBP_BID_PLACED",
      "created_at": "2026-02-19T10:30:00.000Z",
      "data": {
        "wallet": "0x9F1c...",
        "amount_usdc": 1000
      },
      "hash_b64u": "base64url-encoded-SHA256-hash",
      "sig_b64u": "base64url-encoded-HMAC-signature"
    }
  ]
}
        

GET /v1/lbp/auctions/{id}/receipt

Get a signed receipt (evidence capsule) for the current auction state. Can be used for independent verification, compliance auditing, and dispute resolution.

Path Parameters

Parameter	Type	Required	Description
`id`	string (UUID)	required	Auction ID

Response (200 OK)

{
  "ok": true,
  "receipt": {
    "receipt_type": "LBP_AUCTION_STATE",
    "subject_id": "550e8400-e29b-41d4-a716-446655440000",
    "issued_at": "2026-02-19T12:00:00.000Z",
    "auction": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "pair": "JIL/USDC",
      "status": "active",
      "bids": 42,
      "total_volume_usdc": 125000
    },
    "hash_b64u": "receipt-SHA256-content-hash",
    "sig_b64u": "receipt-HMAC-signature"
  }
}
        

Evidence Capsules: Receipts are self-contained evidence capsules that include the auction state snapshot, a SHA-256 content hash, and an HMAC signature. These can be independently verified by any party holding the public verification key, providing tamper-proof audit trails for token launch operations.

Administration

POST /v1/lbp/reset

Reset all auction and journal data. Available on devnet only. Requires the x-devnet-key header matching the DEVNET_ADMIN_KEY environment variable.

Destructive Action: This endpoint permanently deletes all auction data, bids, and journal events. It is only available in the devnet environment and cannot be undone. Do not call this endpoint in production.

Request Headers

Header	Required	Description
`x-devnet-key`	required	Admin key for devnet operations (must match `DEVNET_ADMIN_KEY` env var)

Response (200 OK)

{
  "ok": true,
  "reset": true,
  "count": {
    "auctions": 5,
    "journal": 150
  }
}
        

Rate Limiting: All endpoints are rate limited to 120 requests per minute per IP address. Exceeding this limit returns HTTP 429 with a retry_after_ms field indicating when the next request can be made.

Error Codes

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

Error Response Format

{
  "ok": false,
  "error": {
    "code": "AUCTION_NOT_FOUND",
    "message": "No auction found with the specified ID",
    "details": {
      "auction_id": "550e8400-e29b-41d4-a716-446655440000"
    }
  }
}
        

HTTP Status Codes

Status	Error Code	Description
`400`	`VALIDATION_ERROR`	Request body failed schema validation. Check `details` for field-level errors (e.g., invalid amount, missing required fields).
`403`	`INVALID_ADMIN_KEY`	The `x-devnet-key` header is missing or does not match the configured admin key.
`404`	`AUCTION_NOT_FOUND`	No auction exists with the specified ID.
`429`	`RATE_LIMIT_EXCEEDED`	Too many requests. Includes `retry_after_ms` field indicating when the next request is allowed.

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

Overview

Base URLs

Protocol

GET /health

Response (200 OK)

GET /metrics

Auction Management

GET /v1/lbp/auctions

Response (200 OK)

POST /v1/lbp/auctions

Request Body

Response (201 Created)

POST /v1/lbp/auctions/{id}/close

Path Parameters

Response (200 OK)

Bidding

POST /v1/lbp/auctions/{id}/bid

Path Parameters

Request Body

Response (200 OK)

Journal & Receipts

GET /v1/lbp/auctions/{id}/journal

Path Parameters

Response (200 OK)

GET /v1/lbp/auctions/{id}/receipt

Path Parameters

Response (200 OK)

Administration

POST /v1/lbp/reset

Request Headers

Response (200 OK)

Error Codes

Error Response Format

HTTP Status Codes