# Sparkle Protocol API Usage Guide

How to integrate Sparkle Protocol into wallets, marketplaces, and tools.

---

## Overview

Sparkle Protocol uses JSON metadata inscribed on Bitcoin. Integration involves:

1. Detecting Sparkle inscriptions
2. Parsing JSON metadata
3. Fetching trait images
4. Compositing layers into final images

---

## Detection

### Identify Sparkle Inscriptions

Check if an inscription's content (when parsed as JSON) contains:

```json
{"p": "sparkle"}
```

**Example detection:**

```javascript
async function isSparkleNFT(inscriptionId) {
  const content = await fetchInscriptionContent(inscriptionId);
  try {
    const json = JSON.parse(content);
    return json.p === "sparkle" && json.op === "mint";
  } catch {
    return false;
  }
}
```

---

## Parsing

### NFT Metadata Structure

```json
{
  "p": "sparkle",
  "v": 1,
  "op": "mint",
  "parent": "<genesis_id>",
  "layers": [
    {"id": "<inscription_id>", "z": 0},
    {"id": "<inscription_id>", "z": 1}
  ]
}
```

**Extract trait IDs:**

```javascript
function getTraitIds(metadata) {
  return metadata.layers.map(layer => layer.id);
}
```

---

## Rendering

### Composite NFT Image

```javascript
async function renderSparkleNFT(metadata) {
  const canvas = document.createElement('canvas');
  canvas.width = 1024;
  canvas.height = 1024;
  const ctx = canvas.getContext('2d');

  // Sort layers by z-index
  const sorted = metadata.layers.sort((a, b) => a.z - b.z);

  // Draw each layer
  for (const layer of sorted) {
    const img = await fetchTraitImage(layer.id);
    ctx.drawImage(img, 0, 0, 1024, 1024);
  }

  return canvas.toDataURL();
}

async function fetchTraitImage(inscriptionId) {
  const url = `https://ordinals.com/content/${inscriptionId}`;
  const response = await fetch(url);
  const blob = await response.blob();
  return createImageBitmap(blob);
}
```

---

## Full Implementation Example

See [sparkle-protocol-real.js](https://github.com/SparkleProtocol/sparkle-protocol) for complete reference implementation.

---

**TODO:** This guide will be expanded with more examples and best practices.