### Install Sparkscan Node.js SDK

Source: https://docs.sparkscan.io/sdk/node

Installs the Sparkscan API Node.js SDK client using npm. This is the first step to integrating Sparkscan's services into your server-side Node.js applications.

```bash
npm install @sparkscan/api-node-sdk-client
```

--------------------------------

### Install Sparkscan React SDK

Source: https://docs.sparkscan.io/sdk/js

Installs the Sparkscan React SDK using npm. This package provides hooks for interacting with the Sparkscan API within a React application.

```bash
npm install @sparkscan/api-react-sdk-hooks
```

--------------------------------

### Send Authenticated HTTP Request using cURL

Source: https://docs.sparkscan.io/api-keys

This snippet demonstrates how to make an authenticated HTTP GET request to the Sparkscan API using cURL. It requires an API key to be passed in the 'Authorization' header. The example fetches the latest 5 transactions from the MAINNET.

```curl
curl \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  "https://api.sparkscan.io/v1/tx/latest?network=MAINNET&limit=5"
```

--------------------------------

### Get Token Metadata in Batch

Source: https://docs.sparkscan.io/api/tokens

Retrieves metadata for up to 100 tokens at once.

```APIDOC
## POST /v1/tokens/metadata/batch

### Description
Retrieve metadata for up to 100 tokens at once. Uses Redis cache and RPC nodes as fallback, following the same logic as individual token endpoints.

### Method
POST

### Endpoint
https://api.sparkscan.io/v1/tokens/metadata/batch

### Parameters
#### Query Parameters
- **network** (string) - Required - Enum: REGTEST, MAINNET. The network to query.

#### Request Body
- **token_addresses** (string[]) - Required - Minimum items: 1, Maximum items: 100. List of 66-character hex token addresses.

### Response
#### Success Response (200)
- **metadata** (object[]) - Required - List of token metadata objects.
- **total_count** (integer) - Required - Total number of tokens processed.

#### Response Example
```json
{
  "metadata": [
    {
      "tokenAddress": "0xabc123",
      "name": "Example Token",
      "symbol": "EXM"
    }
  ],
  "total_count": 100
}
```
```

--------------------------------

### Fetch Address Summary (curl)

Source: https://docs.sparkscan.io/introduction

Retrieves a summary of a specific Spark address from the Sparkscan API. This example shows how to query an address on the MAINNET.

```curl
curl "https://api.sparkscan.io/v1/address/sp1pg...zst?network=MAINNET"
```

--------------------------------

### Address Summary API

Source: https://docs.sparkscan.io/api/~schemas

Retrieves a summary of an address, including its public key, balance, and token information. This endpoint is useful for getting a quick overview of an address's holdings and activity.

```APIDOC
## GET /addresses/{address}/summary

### Description
Retrieves a summary of a specific address, including its public key, total balance in USD, transaction count, and token holdings.

### Method
GET

### Endpoint
/addresses/{address}/summary

### Parameters
#### Path Parameters
- **address** (string) - Required - The address to retrieve the summary for.

### Response
#### Success Response (200)
- **sparkAddress** (string) - The Sparkscan address.
- **publicKey** (string) - The public key associated with the address.
- **balance** (object) - An object containing balance information.
  - **totalValueUsd** (number) - The total value of assets held at the address in USD.
  - **transactionCount** (integer) - The total number of transactions associated with the address.
  - **tokenCount** (integer) - The total number of different tokens held at the address.
- **tokens** (array | null) - An array of token objects held at the address, or null if none.

#### Response Example
```json
{
  "sparkAddress": "string",
  "publicKey": "string",
  "balance": {
    "totalValueUsd": 0.0,
    "transactionCount": 0,
    "tokenCount": 0
  },
  "tokens": [
    {
      "tokenIdentifier": "string",
      "tokenAddress": "string",
      "name": "string",
      "ticker": "string",
      "decimals": 0,
      "balance": 0,
      "valueUsd": 0.0,
      "issuerPublicKey": "string",
      "maxSupply": 0,
      "isFreezable": true
    }
  ]
}
```
```

--------------------------------

### Get Address Summary

Source: https://docs.sparkscan.io/introduction

Retrieves a summary of a specific Spark address, including balance and other relevant information.

```APIDOC
## GET /v1/address/{address}

### Description
Retrieves a summary of a specific Spark address.

### Method
GET

### Endpoint
`/v1/address/{address}`

### Parameters
#### Path Parameters
- **address** (string) - Required - The Spark address to query.

#### Query Parameters
- **network** (string) - Optional - Specifies the network to query (e.g., MAINNET, REGTEST). Defaults to MAINNET.

### Response
#### Success Response (200)
- **address** (string) - The queried Spark address.
- **balance** (string) - The current balance of the address.
- **transactionCount** (integer) - The total number of transactions associated with the address.

#### Response Example
```json
{
  "address": "sp1pg...zst",
  "balance": "1234567890",
  "transactionCount": 500
}
```
```

--------------------------------

### Get Address Summary (API)

Source: https://docs.sparkscan.io/api

Retrieves a summary of an address, including its balance, transaction count, and token count. Requires the address and network as parameters.

```http
GET https://api.sparkscan.io/v1/address/{address}?network={network}
```

--------------------------------

### Get Wallet Leaderboard

Source: https://docs.sparkscan.io/api/stats

Retrieves the leaderboard of wallets based on specified network and limit.

```APIDOC
## GET /v1/stats/leaderboard/wallets

### Description
Retrieves the leaderboard of wallets.

### Method
GET

### Endpoint
https://api.sparkscan.io/v1/stats/leaderboard/wallets

### Parameters
#### Query Parameters
- **network** (string) - required - Enum values: REGTEST, MAINNET
- **limit** (integer) - optional - min: 1, max: 100, Default: 25

### Response
#### Success Response (200)
- **leaderboard** (object[]) - required
- **currentBtcPriceUsd** (number)
```

--------------------------------

### Get Token Leaderboard

Source: https://docs.sparkscan.io/api/stats

Retrieves the leaderboard of tokens with options for network, limit, offset, and update time.

```APIDOC
## GET /v1/stats/leaderboard/tokens

### Description
Retrieves the leaderboard of tokens.

### Method
GET

### Endpoint
https://api.sparkscan.io/v1/stats/leaderboard/tokens

### Parameters
#### Query Parameters
- **network** (string) - required - Enum values: REGTEST, MAINNET
- **limit** (integer) - optional - min: 1, max: 100, Default: 25
- **offset** (integer) - optional - min: 0, Default: 0
- **afterUpdatedAt** (string | null) - optional - date-time - Return only tokens whose updatedAt timestamp is after the given ISO timestamp.

### Response
#### Success Response (200)
- **totalTokens** (integer) - required
- **leaderboard** (object[]) - required
```

--------------------------------

### GET /v1/address/{address}

Source: https://docs.sparkscan.io/api/address

Retrieves a summary of a given blockchain address, including its Spark address, public key, balance, and token information.

```APIDOC
## GET /v1/address/{address}

### Description
Retrieves a summary of a given blockchain address, including its Spark address, public key, balance, and token information.

### Method
GET

### Endpoint
https://api.sparkscan.io/v1/address/{address}

### Parameters
#### Path Parameters
- **address** (string) - required - The blockchain address to query.

#### Query Parameters
- **network** (string) - enum - required - The network to query. Enum values: REGTEST, MAINNET

### Response
#### Success Response (200)
- **sparkAddress** (string) - required - The Spark address.
- **publicKey** (string) - required - The public key associated with the address.
- **balance** (object) - required - Contains balance information.
  - **totalValueUsd** (number) - required - The total value of the balance in USD.
  - **transactionCount** (integer) - required - The number of transactions associated with the address.
  - **tokenCount** (integer) - required - The number of tokens held by the address.
- **tokens** (array | null) - List of tokens held by the address.

#### Response Example
```json
{
  "sparkAddress": "0x123abc...",
  "publicKey": "0x456def...",
  "balance": {
    "totalValueUsd": 1500.75,
    "transactionCount": 120,
    "tokenCount": 5
  },
  "tokens": [
    {
      "symbol": "SPARK",
      "balance": "1000000",
      "valueUsd": 1000.00
    }
  ]
}
```
```

--------------------------------

### Get Token Transactions

Source: https://docs.sparkscan.io/api/tokens

Retrieves a list of transactions for a specific token.

```APIDOC
## GET /v1/tokens/{identifier}/transactions

### Description
Retrieves a list of transactions for a specific token.

### Method
GET

### Endpoint
https://api.sparkscan.io/v1/tokens/{identifier}/transactions

### Parameters
#### Path Parameters
- **identifier** (string) - Required - The token identifier.

#### Query Parameters
- **network** (string) - Required - Enum: REGTEST, MAINNET. The network to query.
- **limit** (integer) - Optional - Minimum: 1, Maximum: 100. Default: 25.
- **offset** (integer) - Optional - Minimum: 0. Default: 0.

### Response
#### Success Response (200)
- **meta** (object) - Required - Metadata about the response.
- **data** (object[]) - Required - An array of transaction objects.

#### Response Example
```json
{
  "meta": {
    "count": 100,
    "total": 10000
  },
  "data": [
    {
      "txHash": "0x123abc",
      "from": "addr1",
      "to": "addr2",
      "value": "1000"
    }
  ]
}
```
```

--------------------------------

### Get Token Holders

Source: https://docs.sparkscan.io/api/tokens

Retrieves a list of token holders for a specific token.

```APIDOC
## GET /v1/tokens/{identifier}/holders

### Description
Retrieves a list of token holders for a specific token.

### Method
GET

### Endpoint
https://api.sparkscan.io/v1/tokens/{identifier}/holders

### Parameters
#### Path Parameters
- **identifier** (string) - Required - The token identifier.

#### Query Parameters
- **network** (string) - Required - Enum: REGTEST, MAINNET. The network to query.
- **limit** (integer) - Optional - Minimum: 1, Maximum: 100. Default: 25.
- **offset** (integer) - Optional - Minimum: 0. Default: 0.

### Response
#### Success Response (200)
- **meta** (object) - Required - Metadata about the response.
- **data** (object[]) - Required - An array of holder objects.

#### Response Example
```json
{
  "meta": {
    "count": 50,
    "total": 5000
  },
  "data": [
    {
      "address": "addr1",
      "balance": "500000"
    }
  ]
}
```
```

--------------------------------

### Get Address Summary

Source: https://docs.sparkscan.io/api/address

Retrieves a summary of an address, including its balance, transaction count, and token count. Requires the address and network as parameters.

```HTTP
GET https://api.sparkscan.io/v1/address/{address}?network=MAINNET
```

--------------------------------

### Get Address Tokens API

Source: https://docs.sparkscan.io/api

Retrieves a list of tokens held by a given address.

```APIDOC
## GET /v1/address/{address}/tokens

### Description
Retrieves a list of tokens held by a given address.

### Method
GET

### Endpoint
https://api.sparkscan.io/v1/address/{address}/tokens

### Parameters
#### Path Parameters
- **address** (string) - required - The address to retrieve tokens for.

#### Query Parameters
- **network** (string) - enum - required - Specifies the network. Enum values: REGTEST, MAINNET.

### Response
#### Success Response (200)
- **address** (string) - required - The address.
- **pubkey** (string) - required - The public key.
- **totalValueUsd** (number) - float - required - The total USD value of all tokens held by the address.
- **tokens** (object[]) - required - An array of token objects.
  - **symbol** (string) - The token symbol.
  - **valueUsd** (number) - The USD value of the token.
  - **amount** (string) - The amount of the token held.

#### Response Example
```json
{
  "address": "spark1qx484w4w4w4w4w4w4w4w4w4w4w4w4w4w4w4w4w",
  "pubkey": "02abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
  "totalValueUsd": 1500.75,
  "tokens": [
    {
      "symbol": "SPARK",
      "valueUsd": 1000.50,
      "amount": "1000000"
    },
    {
      "symbol": "XYZ",
      "valueUsd": 500.25,
      "amount": "50000"
    }
  ]
}
```
```

--------------------------------

### Get Address Tokens (API)

Source: https://docs.sparkscan.io/api

Retrieves a list of tokens held by a specific address. Requires the address and network as parameters.

```http
GET https://api.sparkscan.io/v1/address/{address}/tokens?network={network}
```

--------------------------------

### Get Address Transactions API

Source: https://docs.sparkscan.io/api

Retrieves a list of transactions for a given address, with options for filtering and pagination.

```APIDOC
## GET /v1/address/{address}/transactions

### Description
Retrieves a list of transactions for a given address, with options for filtering and pagination.

### Method
GET

### Endpoint
https://api.sparkscan.io/v1/address/{address}/transactions

### Parameters
#### Path Parameters
- **address** (string) - required - The address to retrieve transactions for.

#### Query Parameters
- **network** (string) - enum - required - Specifies the network. Enum values: REGTEST, MAINNET.
- **limit** (integer) - Optional - The maximum number of transactions to return. Minimum: 1, Maximum: 100. Defaults to 25.
- **offset** (integer) - Optional - The number of transactions to skip. Minimum: 0. Defaults to 0.
- **asset** (string | null) - Optional - Filters transactions by asset. Use 'btc' for Bitcoin-only or a token identifier/address to filter token transactions.

### Response
#### Success Response (200)
- **meta** (object) - required - Metadata about the response.
- **data** (object[]) - required - An array of transaction objects.

#### Response Example
```json
{
  "meta": {
    "count": 10,
    "total": 100
  },
  "data": [
    {
      "txid": "a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef1234567890",
      "from": "spark1abcdef...",
      "to": "spark1ghijkl...",
      "value": "100000",
      "asset": "SPARK",
      "timestamp": "2023-10-27T10:00:00Z"
    },
    {
      "txid": "f6e5d4c3b2a10987fedcba0123456789fedcba0123456789fedcba0123456789",
      "from": "spark1ghijkl...",
      "to": "spark1mnopqr...",
      "value": "50000",
      "asset": "XYZ",
      "timestamp": "2023-10-27T09:30:00Z"
    }
  ]
}
```
```

--------------------------------

### Fetch Latest Spark Transactions (curl)

Source: https://docs.sparkscan.io/introduction

Retrieves the latest Spark transactions from the Sparkscan API. This example demonstrates how to fetch a specific number of transactions for the MAINNET.

```curl
curl "https://api.sparkscan.io/v1/tx/latest?network=MAINNET&limit=5"
```

--------------------------------

### Get Token Details by Pubkey or Search Tokens

Source: https://docs.sparkscan.io/api/tokens

Retrieves details for a specific token using its public key or address. If the identifier is not a valid token identifier, it's treated as a search query.

```APIDOC
## GET /v1/tokens/{identifier}

### Description
If the path segment is a 64-character hex token identifier or a Bech32 token address, returns its details. Otherwise the segment is treated as a search query over token name, ticker or address.

### Method
GET

### Endpoint
https://api.sparkscan.io/v1/tokens/{identifier}

### Parameters
#### Path Parameters
- **identifier** (string) - Required - The token identifier (public key or address) or a search query.

#### Query Parameters
- **network** (string) - Required - Enum: REGTEST, MAINNET. The network to query.
- **limit** (integer) - Optional - Minimum: 1, Maximum: 100. Limit for search results if identifier is a query string. Default: 25.
- **offset** (integer) - Optional - Minimum: 0. Offset for search results if identifier is a query string. Default: 0.

### Response
#### Success Response (200)
- **metadata** (object) - Required - Token metadata.
- **totalSupply** (integer) - Required - The total supply of the token.
- **marketCapUsd** (number) - Required - The market capitalization in USD.
- **volume24hUsd** (number) - Required - The 24-hour trading volume in USD.

#### Response Example
```json
{
  "metadata": {
    "name": "Example Token",
    "symbol": "EXM",
    "decimals": 6
  },
  "totalSupply": 1000000000,
  "marketCapUsd": 50000000.0,
  "volume24hUsd": 100000.0
}
```
```

--------------------------------

### GET /v1/address/{address}/tokens

Source: https://docs.sparkscan.io/api/address

Retrieves a list of tokens associated with a given blockchain address, including their value in USD.

```APIDOC
## GET /v1/address/{address}/tokens

### Description
Retrieves a list of tokens associated with a given blockchain address, including their value in USD.

### Method
GET

### Endpoint
https://api.sparkscan.io/v1/address/{address}/tokens

### Parameters
#### Path Parameters
- **address** (string) - required - The blockchain address to query.

#### Query Parameters
- **network** (string) - enum - required - The network to query. Enum values: REGTEST, MAINNET

### Response
#### Success Response (200)
- **address** (string) - required - The blockchain address.
- **pubkey** (string) - required - The public key associated with the address.
- **totalValueUsd** (number) - float - required - The total value of all tokens in USD.
- **tokens** (object[]) - required - An array of token objects.

#### Response Example
```json
{
  "address": "0x123abc...",
  "pubkey": "0x456def...",
  "totalValueUsd": 1000.00,
  "tokens": [
    {
      "symbol": "SPARK",
      "balance": "1000000",
      "valueUsd": 1000.00
    },
    {
      "symbol": "USDCT",
      "balance": "500000",
      "valueUsd": 500.00
    }
  ]
}
```
```

--------------------------------

### Get Wallet Leaderboard API Request

Source: https://docs.sparkscan.io/api/stats

Retrieves the leaderboard of wallets based on specified network and limit parameters. The network parameter is required and must be either 'REGTEST' or 'MAINNET'. The limit parameter is optional, with a default value of 25 and a maximum of 100.

```HTTP
GET https://api.sparkscan.io/v1/stats/leaderboard/wallets?network=MAINNET&limit=50
```

--------------------------------

### Get Address Transactions (API)

Source: https://docs.sparkscan.io/api

Fetches a list of transactions associated with a specific address. Supports filtering by network, limit, offset, and asset.

```http
GET https://api.sparkscan.io/v1/address/{address}/transactions?network={network}&limit={limit}&offset={offset}&asset={asset}
```

--------------------------------

### Get Address Tokens

Source: https://docs.sparkscan.io/api/address

Retrieves a list of tokens associated with a specific address, including their total value in USD. Requires the address and network as parameters.

```HTTP
GET https://api.sparkscan.io/v1/address/{address}/tokens?network=REGTEST
```

--------------------------------

### Security Best Practices

Source: https://docs.sparkscan.io/api-keys

Guidelines for securely handling and using API keys.

```APIDOC
## Security Best Practices

* Store keys as environment variables, **never** commit them to source control.
* Rotate keys periodically and immediately revoke leaked keys.
* Do not bundle API keys with your browser extensions or mobile apps.
```

--------------------------------

### API Authentication and Usage

Source: https://docs.sparkscan.io/api-keys

Demonstrates how to use the obtained API key for authentication and making requests to the Sparkscan API.

```APIDOC
## Using Your Key

Add the header `Authorization` to every HTTP request:

```curl
curl \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  "https://api.sparkscan.io/v1/tx/latest?network=MAINNET&limit=5"
```
```

--------------------------------

### Fetch Address Summary using Sparkscan Node.js SDK

Source: https://docs.sparkscan.io/sdk/node

Demonstrates how to fetch address summary information using the Sparkscan Node.js SDK. It requires the Satoshi's address and an API key for authentication. The function returns address details, which are then logged to the console.

```javascript
import { addressSummaryV1AddressAddressGet } from '@sparkscan/api-node-sdk-client';

(async () => {
  const addressInfo = await addressSummaryV1AddressAddressGet(
    'sp1...xyz', // Satoshi's address
    { network: 'MAINNET' },
    {
      headers: {
        'Authorization': 'Bearer <YOUR_API_KEY>'
      }
    }
  );
  console.log(addressInfo);
})();
```

--------------------------------

### Obtain API Key

Source: https://docs.sparkscan.io/api-keys

Steps to generate an API key from the Sparkscan website dashboard.

```APIDOC
## Obtaining an API Key

1. Sign-in on the Sparkscan website (top-right door button).
2. Navigate to the dashboard and click on **API Keys**.
3. Give your key a name (e.g. _my-backend_), and click **Create**.
4. Copy the value.
```

--------------------------------

### WalletLeaderboard Data Structure

Source: https://docs.sparkscan.io/api/~schemas

Outlines the structure for the wallet leaderboard response.

```APIDOC
## WalletLeaderboard

### Description
Contains data for the wallet leaderboard.

### Properties
* `leaderboard` (array) - Required - An array of leaderboard entries.
* `currentBtcPriceUsd` (number) - The current Bitcoin price in USD. Default: 0.
```

--------------------------------

### Fetch Network Statistics with useNetworkStats Hook

Source: https://docs.sparkscan.io/sdk/js

Demonstrates how to use the `useNetworkStats` hook from the Sparkscan React SDK to fetch and display network statistics. It handles loading and error states, and displays the total value locked in sats.

```javascript
import { useNetworkStats } from '@sparkscan/api-react-sdk-hooks';

function Dashboard() {
  const { data, loading, error } = useNetworkStats({ network: 'MAINNET' });

  if (loading) return <p>Loading…</p>;
  if (error) return <p>Error: {error.message}</p>;

  return <p>TVL: {data.totalValueLockedSats} sats</p>;
}
```

--------------------------------

### BalancePayload Schema Excerpt (JSON)

Source: https://docs.sparkscan.io/live/balances-channel

An excerpt of the JSON schema for the BalancePayload, detailing the structure of real-time balance updates. It includes fields like address, network, balances, and processing timestamp. This schema defines the data format for messages received from the balances channel.

```json
{
  "address": "sp1pg...zst",
  "network": "MAINNET",
  "soft_balance": "379",
  "hard_balance": "301",
  "processed_at": "2025-08-02T20:02:54.035Z"
}
```

--------------------------------

### Lookup token ↔ issuer pubkey

Source: https://docs.sparkscan.io/api/tokens

Convert issuer public keys to their token identifier/address or vice-versa. Accepts up to 100 items per request.

```APIDOC
## POST /v1/tokens/issuer-lookup

### Description
Convert issuer public keys to their token identifier/address or vice-versa. Accepts up to 100 items per request.

### Method
POST

### Endpoint
https://api.sparkscan.io/v1/tokens/issuer-lookup

### Parameters
#### Query Parameters
- **network** (string) - Required - Enum: REGTEST, MAINNET. The network to query.

#### Request Body
- **pubkeys** (array | null) - Maximum items: 100. Array of issuer public keys.
- **tokens** (array | null) - Maximum items: 100. Array of token identifiers/addresses.

### Response
#### Success Response (200)
- **results** (object[]) - Required - Results of the lookup.

#### Response Example
```json
{
  "results": [
    {
      "pubkey": "0x123abc",
      "tokenAddress": "0x456def"
    }
  ]
}
```
```

--------------------------------

### Token Holders

Source: https://docs.sparkscan.io/api/~schemas

Retrieves a list of token holders, their balances, and their value in USD.

```APIDOC
## GET /tokens/{tokenIdentifier}/holders

### Description
Retrieves a paginated list of token holders, including their Spark address, public key, token balance, value in USD, and percentage of total supply.

### Method
GET

### Endpoint
/tokens/{tokenIdentifier}/holders

### Parameters
#### Path Parameters
- **tokenIdentifier** (string) - Required - The unique identifier of the token.

#### Query Parameters
- **limit** (integer) - Optional - The maximum number of holders to return per page.
- **offset** (integer) - Optional - The number of holders to skip before returning results.

### Request Example
None

### Response
#### Success Response (200)
- **meta** (object) - Metadata about the response, including total items, limit, and offset.
- **data** (array) - An array of token holder objects.
  - **address** (string) - Required - The Spark address of the holder.
  - **pubkey** (string) - Required - The public key of the holder.
  - **balance** (integer) - Required - The token balance of the holder.
  - **valueUsd** (number) - Required - The value of the holder's balance in USD.
  - **percentage** (number) - Required - The percentage of the total token supply held by this holder.

#### Response Example
```json
{
  "meta": {
    "totalItems": 1500,
    "limit": 100,
    "offset": 0
  },
  "data": [
    {
      "address": "SPK123abc...",
      "pubkey": "04abcdef123...",
      "balance": 1000000,
      "valueUsd": 10000,
      "percentage": 0.1
    }
  ]
}
```
```

--------------------------------

### Get Latest Transactions

Source: https://docs.sparkscan.io/api/tx

Retrieves a list of the latest transactions from the Sparkscan API. Supports filtering by network, limit, timestamps, and offset.

```APIDOC
## GET /v1/tx/latest

### Description
Retrieves a list of the latest transactions. You can filter by network, limit the number of results, set an offset, and specify a time range using `from_timestamp` and `to_timestamp`.

### Method
GET

### Endpoint
`https://api.sparkscan.io/v1/tx/latest`

### Parameters
#### Query Parameters
- **network** (string) - enum (REGTEST, MAINNET) - required - Specifies the network to query.
- **limit** (integer) - min: 1, max: 500 - optional - The maximum number of transactions to return. Defaults to 10.
- **offset** (integer) - min: 0 - optional - The number of transactions to skip. Defaults to 0.
- **from_timestamp** (string | null) - date-time - optional - Return transactions created at or after this ISO timestamp.
- **to_timestamp** (string | null) - date-time - optional - Return transactions created at or before this ISO timestamp.

### Response
#### Success Response (200)
- **id** (string) - Transaction ID (UUID for Spark/LN, hash for BTC/Token).
- **type** (string) - enum (bitcoin_deposit, bitcoin_withdrawal, spark_transfer, lightning_payment, token_mint, token_transfer, token_burn, token_multi_transfer) - The type of the transaction.
- **status** (string) - enum (confirmed, pending, sent, failed, expired) - The current status of the transaction.
- **valueUsd** (number) - The value of the transaction in USD.
- **createdAt** (string | null) - date-time - When the transaction was first recorded/broadcast.
- **updatedAt** (string | null) - date-time - Last update/completion timestamp.
- **amountSats** (integer | null) - The transaction amount in satoshis.
- **tokenAmount** (integer | null) - The token amount for token-related transactions.
- **tokenMetadata** (object) - Metadata for token transactions.
- **multiIoDetails** (object) - Details for multi-input/output transactions.
- **from** (object) - Information about the sender.
- **to** (object) - Information about the receiver.
- **bitcoinTxid** (string | null) - The Bitcoin transaction ID if applicable.

#### Response Example
{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "type": "spark_transfer",
  "status": "confirmed",
  "valueUsd": 150.75,
  "createdAt": "2023-10-27T10:00:00Z",
  "updatedAt": "2023-10-27T10:01:00Z",
  "amountSats": 3000000,
  "tokenAmount": null,
  "tokenMetadata": null,
  "multiIoDetails": null,
  "from": {
    "address": "spark123abc",
    "type": "spark"
  },
  "to": {
    "address": "spark456def",
    "type": "spark"
  },
  "bitcoinTxid": null
}
```

--------------------------------

### GET /v1/address/{address}/transactions

Source: https://docs.sparkscan.io/api/address

Retrieves a list of transactions associated with a given blockchain address, with options for pagination and asset filtering.

```APIDOC
## GET /v1/address/{address}/transactions

### Description
Retrieves a list of transactions associated with a given blockchain address, with options for pagination and asset filtering.

### Method
GET

### Endpoint
https://api.sparkscan.io/v1/address/{address}/transactions

### Parameters
#### Path Parameters
- **address** (string) - required - The blockchain address to query.

#### Query Parameters
- **network** (string) - enum - required - The network to query. Enum values: REGTEST, MAINNET
- **limit** (integer) - Optional - Maximum number of transactions to return (min: 1, max: 100). Defaults to 25.
- **offset** (integer) - Optional - Number of transactions to skip (min: 0). Defaults to 0.
- **asset** (string | null) - Optional - Filter transactions by asset. Use 'btc' for Bitcoin-only or a token identifier/address to filter token transactions.

### Response
#### Success Response (200)
- **meta** (object) - required - Metadata about the response.
- **data** (object[]) - required - An array of transaction objects.

#### Response Example
```json
{
  "meta": {
    "count": 10,
    "total": 120
  },
  "data": [
    {
      "txid": "0xabc123...",
      "from": "0x123abc...",
      "to": "0x456def...",
      "value": "1000000",
      "timestamp": 1678886400
    }
  ]
}
```
```

--------------------------------

### Address Summary API

Source: https://docs.sparkscan.io/api

Retrieves a summary of a given address, including its Spark Address, public key, balance, and token information.

```APIDOC
## GET /v1/address/{address}

### Description
Retrieves a summary of a given address, including its Spark Address, public key, balance, and token information.

### Method
GET

### Endpoint
https://api.sparkscan.io/v1/address/{address}

### Parameters
#### Path Parameters
- **address** (string) - required - The address to retrieve information for.

#### Query Parameters
- **network** (string) - enum - required - Specifies the network. Enum values: REGTEST, MAINNET.

### Response
#### Success Response (200)
- **sparkAddress** (string) - required - The Spark Address.
- **publicKey** (string) - required - The public key associated with the address.
- **balance** (object) - required - An object containing balance details.
  - **totalValueUsd** (number) - required - The total value of the balance in USD.
  - **transactionCount** (integer) - required - The total number of transactions for the address.
  - **tokenCount** (integer) - required - The total number of tokens associated with the address.
- **tokens** (array | null) - A list of tokens associated with the address, or null if none.

#### Response Example
```json
{
  "sparkAddress": "spark1qx484w4w4w4w4w4w4w4w4w4w4w4w4w4w4w4w4w",
  "publicKey": "02abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
  "balance": {
    "totalValueUsd": 1500.75,
    "transactionCount": 50,
    "tokenCount": 5
  },
  "tokens": [
    {
      "symbol": "SPARK",
      "valueUsd": 1000.50,
      "amount": "1000000"
    },
    {
      "symbol": "XYZ",
      "valueUsd": 500.25,
      "amount": "50000"
    }
  ]
}
```
```

--------------------------------

### Token Details

Source: https://docs.sparkscan.io/api/~schemas

Retrieves detailed metadata for a specific token, including its market cap and 24-hour volume.

```APIDOC
## GET /tokens/{tokenIdentifier}

### Description
Retrieves detailed metadata for a specific token, including its total supply, market capitalization, and 24-hour trading volume.

### Method
GET

### Endpoint
/tokens/{tokenIdentifier}

### Parameters
#### Path Parameters
- **tokenIdentifier** (string) - Required - The unique identifier of the token.

#### Query Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **metadata** (object) - Required - Contains token metadata.
  - **totalSupply** (integer) - Total supply of the token.
  - **marketCapUsd** (number) - Market capitalization of the token in USD.
  - **volume24hUsd** (number) - Trading volume of the token in USD over the last 24 hours.

#### Response Example
```json
{
  "metadata": {
    "totalSupply": 1000000000,
    "marketCapUsd": 100000000,
    "volume24hUsd": 5000000
  }
}
```
```

--------------------------------

### Get Transaction Details by ID

Source: https://docs.sparkscan.io/api/tx

Retrieves detailed information for a specific transaction using its ID or hash. Supports both Spark/Bitcoin/Lightning/Token transactions.

```APIDOC
## GET /v1/tx/{txid}

### Description
Retrieves detailed information about a specific transaction (Spark, Bitcoin, Lightning, or Token) by its ID or hash. Requires the transaction ID and the network.

### Method
GET

### Endpoint
`https://api.sparkscan.io/v1/tx/{txid}`

### Parameters
#### Path Parameters
- **txid** (string) - required - The ID or hash of the transaction.

#### Query Parameters
- **network** (string) - enum (REGTEST, MAINNET) - required - Specifies the network the transaction belongs to.

### Response
#### Success Response (200)
This endpoint can return different response structures based on the transaction type. The response will match either `TxV1Response` or `TokenTransaction`.

**Properties for TxV1Response:**
- **id** (string) - The transaction ID.
- **type** (string) - The type of the transaction.
- **status** (string) - enum (confirmed, pending, sent, failed, expired) - The status of the transaction.
- **amountSats** (integer) - The transaction amount in satoshis.
- **valueUsd** (number) - float - The value of the transaction in USD.
- **createdAt** (string | null) - date-time - When the transaction was first recorded/initiated.
- **updatedAt** (string | null) - date-time - Last update/completion timestamp.
- **from** (object) - Information about the sender.
- **to** (object) - Information about the receiver.
- **timeTakenSeconds** (number | null) - float - Duration of the transaction in seconds.
- **txid** (string | null) - The Bitcoin transaction ID if applicable.
- **bitcoinTxData** (object) - Additional Bitcoin transaction data.

**Properties for TokenTransaction:**
(Similar to TxV1Response but with token-specific fields like `tokenAmount`, `tokenMetadata`, etc. - Details omitted for brevity but would be present in a full OpenAPI spec).

#### Response Example (TxV1Response)
{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "type": "lightning_payment",
  "status": "confirmed",
  "amountSats": 500000,
  "valueUsd": 10.50,
  "createdAt": "2023-10-27T11:30:00Z",
  "updatedAt": "2023-10-27T11:30:05Z",
  "from": {
    "address": "lightning_node_1",
    "type": "lightning"
  },
  "to": {
    "address": "lightning_node_2",
    "type": "lightning"
  },
  "timeTakenSeconds": 5,
  "txid": "a1b2c3d4e5f67890",
  "bitcoinTxData": {
    "feeSat": 1000
  }
}
```

--------------------------------

### WalletLeaderboardEntry Data Structure

Source: https://docs.sparkscan.io/api/~schemas

Defines the structure for an individual entry in the wallet leaderboard.

```APIDOC
## WalletLeaderboardEntry

### Description
Represents a single entry in the wallet leaderboard.

### Properties
* `rank` (integer) - Required - The rank of the address on the leaderboard.
* `sparkAddress` (string) - Required - The SparkScan address.
* `pubkey` (string) - Required - The public key associated with the address.
* `totalValueSats` (integer) - Required - The total value held by the address in satoshis.
* `totalValueUsd` (number) - The total value held by the address in USD. Default: 0.
```

--------------------------------

### Token API

Source: https://docs.sparkscan.io/index

Endpoints for interacting with Spark tokens, including metadata lookup and retrieving token-specific data.

```APIDOC
## GET /v1/tokens/{identifier}

### Description
Looks up token metadata or searches for tokens by name or ticker symbol.

### Method
GET

### Endpoint
/v1/tokens/{identifier}

#### Path Parameters
- **identifier** (string) - Required - The token ID, name, or ticker symbol to search for.

#### Query Parameters
- **network** (string) - Optional - Specifies the network ('MAINNET' or 'REGTEST'). Defaults to 'MAINNET'.

### Request Example
```
GET /v1/tokens/SPRK?network=MAINNET HTTP/1.1
Host: api.sparkscan.io
```

### Response
#### Success Response (200)
- **token_id** (string) - The unique identifier for the token.
- **symbol** (string) - The token symbol.
- **name** (string) - The name of the token.
- **description** (string) - A brief description of the token.
- **decimals** (integer) - The number of decimal places for the token.

#### Response Example
```json
{
  "token_id": "tk_abc123",
  "symbol": "SPRK",
  "name": "Spark Token",
  "description": "The native token of the Spark network.",
  "decimals": 8
}
```

## POST /v1/tokens/batch

### Description
Performs a batch metadata lookup for up to 100 tokens.

### Method
POST

### Endpoint
/v1/tokens/batch

#### Query Parameters
- **network** (string) - Optional - Specifies the network ('MAINNET' or 'REGTEST'). Defaults to 'MAINNET'.

#### Request Body
- **token_ids** (array) - Required - An array of token IDs or symbols (up to 100).
  - Each element should be a string representing a token identifier.

### Request Example
```json
{
  "token_ids": [
    "SPRK",
    "tk_xyz789",
    "BTC"
  ]
}
```

### Response
#### Success Response (200)
- **tokens** (array) - A list of token metadata objects.
  - **token_id** (string) - The unique identifier for the token.
  - **symbol** (string) - The token symbol.
  - **name** (string) - The name of the token.

#### Response Example
```json
{
  "tokens": [
    {
      "token_id": "tk_abc123",
      "symbol": "SPRK",
      "name": "Spark Token"
    },
    {
      "token_id": "tk_xyz789",
      "symbol": "XYZ",
      "name": "XYZ Coin"
    }
  ]
}
```
```