Coordinator API

1. Overview (Legacy Coordinator Model)

This page documents the original coordinator API concept. A Sparkle coordinator is a service that facilitates Lightning/Spark-based Ordinal trades. The coordinator:

1. Accepts a sparkle_checkout object
2. Validates pricing and inscription ownership
3. Generates Lightning/Spark invoice
4. Monitors for payment completion
5. Executes on-chain Ordinal transfer

Note: This documentation describes a legacy API specification. The current implementation uses decentralized Nostr-based coordination instead.

2. API Endpoints

2.1 POST /api/checkout/prepare

Initiates a Lightning/Spark checkout for an Ordinal inscription.

Request Body

{
  "p": "sparkle",
  "op": "checkout",
  "version": 1,
  "inscription_id": "abc123...i0",
  "collection_ref": "def456...i0",
  "buyer": {
    "ord_address": "bc1p...buyer...",
    "lightning_address": "buyer@example.com"
  },
  "network": "spark",
  "max_total_sats": 1500000,
  "pricing": {
    "seller_sats": 1400000,
    "creator_royalty_sats": 20000,
    "market_fee_sats": 30000,
    "estimated_l1_fee_sats": 50000
  },
  "market": {
    "id": "example.market",
    "name": "Example Market"
  },
  "expiry_block": 900000
}

Response

{
  "checkout_id": "chk_1234567890",
  "status": "pending_payment",
  "invoice": "lnbc15000000...",
  "expires_at": 1234567890,
  "payment_request": {
    "type": "spark",
    "lightning_address": "coordinator@example.com",
    "amount_sats": 1500000,
    "memo": "Darkita #1234 via Sparkle"
  }
}

Error Responses

2.2 POST /api/checkout/status

Retrieves the current status of an ongoing checkout.

Request Body

{
  "checkout_id": "chk_1234567890"
}

Response

{
  "checkout_id": "chk_1234567890",
  "status": "confirmed",
  "inscription_id": "abc123...i0",
  "payment": {
    "received_sats": 1500000,
    "confirmed_at": 1234567890
  },
  "transfer": {
    "txid": "fedcba987654321...",
    "vout": 0,
    "confirmations": 2
  }
}

Status Values

2.3 GET /api/health

Health check endpoint for monitoring.

Response

{
  "status": "ok",
  "version": "1.0.0",
  "network": "mainnet",
  "lightning": {
    "connected": true,
    "node_id": "03abc..."
  },
  "bitcoin": {
    "connected": true,
    "block_height": 900000
  }
}

3. Implementation Requirements

3.1 Validation

Coordinators MUST validate incoming checkout requests:

• Verify JSON structure matches sparkle_checkout specification
• Confirm max_total_sats equals sum of pricing fields
• Verify inscription ownership (seller controls UTXO)
• Validate royalty against genesis declaration
• Ensure inscription is not locked in another checkout

3.2 Lightning Integration

Coordinators MUST handle Lightning payments:

• Generate invoice for max_total_sats amount
• For Spark network: Use UMA protocol for addressing
• For ln-mainnet: Standard BOLT11 invoice
• Monitor for payment within expiry window
• Handle partial payments appropriately

3.3 Ordinal Transfer

Coordinators MUST execute on-chain transfers:

• Construct transaction with inscription input
• Output to buyer's ord_address
• Include appropriate fee for timely confirmation
• Broadcast and monitor for confirmations
• Support RBF if initial fee is insufficient

3.4 Fee Distribution

Coordinators MUST distribute funds correctly:

• Send seller_sats to seller
• Send creator_royalty_sats to creator
• Retain market_fee_sats as coordinator fee
• Use estimated_l1_fee_sats for on-chain transfer

4. Example Integration

// JavaScript Example

// 1. Prepare checkout
const checkout = {
  p: "sparkle",
  op: "checkout",
  version: 1,
  inscription_id: "abc123...i0",
  collection_ref: "def456...i0",
  buyer: {
    ord_address: "bc1p...buyer...",
    lightning_address: "alice@example.com"
  },
  network: "spark",
  max_total_sats: 1500000,
  pricing: {
    seller_sats: 1400000,
    creator_royalty_sats: 70000,
    market_fee_sats: 20000,
    estimated_l1_fee_sats: 10000
  }
};

// 2. Send to coordinator
const response = await fetch('/api/checkout/prepare', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(checkout)
});

const { checkout_id, invoice } = await response.json();

// 3. Poll for status
const checkStatus = async () => {
  const status = await fetch('/api/checkout/status', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ checkout_id })
  });

  const result = await status.json();

  if (result.status === 'confirmed') {
    console.log('Transfer complete:', result.transfer.txid);
  } else if (result.status !== 'failed') {
    setTimeout(checkStatus, 5000);
  }
};

checkStatus();

5. Deployment Guide

5.1 Serverless Setup (Recommended)

No server deployment required. Users connect directly via the Swap Interface.

1. Install a Nostr browser extension: Alby, nos2x, or similar NIP-07 compatible wallet
2. Install a Bitcoin wallet: Unisat, Xverse, or similar for PSBT signing
3. Connect to relays: Default relays are pre-configured, or add custom relays
4. Start trading: List inscriptions or browse available offers

5.2 Self-Hosted Coordinator (Advanced)

For marketplaces or high-volume traders who want dedicated infrastructure.

Prerequisites

• Node.js v18+ or Bun runtime
• LND v0.18+ with hold invoice support
• Bitcoin Core (fully synced) or Electrum server access
• PostgreSQL or SQLite for state management

Installation

# Clone the SDK repository
git clone https://github.com/ProtocolSparkle/Sparkles-Protocol.git
cd Sparkles-Protocol

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env with your LND credentials and Bitcoin RPC

# Run coordinator service
npm run coordinator

Configuration

# .env configuration
LND_MACAROON_PATH=/path/to/admin.macaroon
LND_CERT_PATH=/path/to/tls.cert
LND_HOST=localhost:10009

BITCOIN_RPC_HOST=localhost
BITCOIN_RPC_PORT=8332
BITCOIN_RPC_USER=your_user
BITCOIN_RPC_PASS=your_password

# Coordinator settings
COORDINATOR_FEE_SATS=1000
MIN_LOCKTIME_BLOCKS=6
MAX_TRADE_AMOUNT_SATS=10000000

Security Considerations

• Never expose LND admin macaroon publicly - Use invoice-only macaroon for public endpoints
• Rate limiting: Implement request throttling to prevent abuse
• HTTPS required: All production endpoints must use TLS
• Monitoring: Set up alerts for failed transactions and unusual activity

6. Coordinator Trust Model

Mitigations

• Multiple coordinators: Use different coordinators for different trades to reduce single-point trust
• Self-hosted option: Run your own coordinator for complete control (see Section 5.2)
• Nostr-based trading: The serverless Nostr approach eliminates centralized coordinators entirely
• Timelock protection: Sellers can always recover inscriptions after timelock expiry if trades stall

Bottom line: The coordinator facilitates trades but cannot steal. This is similar to how a Bitcoin mempool relayer can censor but not forge transactions. For maximum trustlessness, use the serverless Nostr-based swap interface.