{
"openapi": "3.0.2",
"info": {
"title": "Sparkscan API",
"description": "API for Sparkscan - a Spark wallet explorer",
"version": "1.3.3"
},
"paths": {
"/": {
"get": {
"summary": "Root",
"operationId": "root__get",
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
}
}
}
},
"/v1/address/{address}": {
"get": {
"tags": [
"Address"
],
"summary": "Address Summary",
"operationId": "address_summary_v1_address__address__get",
"parameters": [
{
"name": "address",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Address"
}
},
{
"name": "network",
"in": "query",
"required": true,
"schema": {
"enum": [
"REGTEST",
"MAINNET"
],
"type": "string",
"title": "Network"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AddressSummaryResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/address/{address}/transactions": {
"get": {
"tags": [
"Address"
],
"summary": "Get Address Transactions",
"operationId": "get_address_transactions_v1_address__address__transactions_get",
"parameters": [
{
"name": "address",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Address"
}
},
{
"name": "network",
"in": "query",
"required": true,
"schema": {
"enum": [
"REGTEST",
"MAINNET"
],
"type": "string",
"title": "Network"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"default": 25,
"title": "Limit"
}
},
{
"name": "offset",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 0,
"default": 0,
"title": "Offset"
}
},
{
"name": "asset",
"in": "query",
"required": false,
"schema": {
"type": "string",
"nullable": true
},
"description": "Optional asset filter. Use 'btc' for Bitcoin-only or a token identifier/address to filter token txs."
},
{
"name": "from_timestamp",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "date-time",
"nullable": true
},
"description": "Return transactions created at or after this ISO timestamp"
},
{
"name": "to_timestamp",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "date-time",
"nullable": true
},
"description": "Return transactions created at or before this ISO timestamp"
},
{
"name": "sort",
"in": "query",
"required": false,
"schema": {
"enum": [
"created_at",
"updated_at"
],
"type": "string",
"description": "Field to sort by (created_at or updated_at)",
"default": "created_at",
"title": "Sort"
},
"description": "Field to sort by (created_at or updated_at)"
},
{
"name": "order",
"in": "query",
"required": false,
"schema": {
"enum": [
"asc",
"desc"
],
"type": "string",
"description": "Sort direction (asc or desc)",
"default": "desc",
"title": "Order"
},
"description": "Sort direction (asc or desc)"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AddressTransactionsResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/tx/latest": {
"get": {
"tags": [
"Tx"
],
"summary": "Get Latest Transactions",
"operationId": "get_latest_transactions_v1_tx_latest_get",
"parameters": [
{
"name": "network",
"in": "query",
"required": true,
"schema": {
"enum": [
"REGTEST",
"MAINNET"
],
"type": "string",
"title": "Network"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 500,
"minimum": 1,
"default": 10,
"title": "Limit"
}
},
{
"name": "offset",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 0,
"default": 0,
"title": "Offset"
}
},
{
"name": "from_timestamp",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "date-time",
"nullable": true
},
"description": "Return transactions created at or after this ISO timestamp"
},
{
"name": "to_timestamp",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "date-time",
"nullable": true
},
"description": "Return transactions created at or before this ISO timestamp"
},
{
"name": "sort",
"in": "query",
"required": false,
"schema": {
"enum": [
"created_at",
"updated_at"
],
"type": "string",
"description": "Field to sort by (created_at or updated_at)",
"default": "created_at",
"title": "Sort"
},
"description": "Field to sort by (created_at or updated_at)"
},
{
"name": "order",
"in": "query",
"required": false,
"schema": {
"enum": [
"asc",
"desc"
],
"type": "string",
"description": "Sort direction (asc or desc)",
"default": "desc",
"title": "Order"
},
"description": "Sort direction (asc or desc)"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/LatestNetworkTransactionItem"
},
"title": "Response Get Latest Transactions V1 Tx Latest Get"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/tx/{txid}": {
"get": {
"tags": [
"Tx"
],
"summary": "Get Transaction Details by ID",
"description": "Retrieves detailed information about a specific transaction (Spark, Bitcoin, Lightning, or Token) by its ID or hash.",
"operationId": "get_transaction_details_by_id_v1_tx__txid__get",
"parameters": [
{
"name": "txid",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Txid"
}
},
{
"name": "network",
"in": "query",
"required": false,
"schema": {
"enum": [
"REGTEST",
"MAINNET"
],
"type": "string",
"nullable": true
},
"description": "Filter by network. If specified, only returns the transaction if it matches this network."
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"$ref": "#/components/schemas/TxV1Response"
},
{
"$ref": "#/components/schemas/TokenTransaction"
}
],
"title": "Response Get Transaction Details By Id V1 Tx Txid Get"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/stats/leaderboard/wallets": {
"get": {
"tags": [
"Stats"
],
"summary": "Get Wallet Leaderboard",
"operationId": "get_wallet_leaderboard_v1_stats_leaderboard_wallets_get",
"parameters": [
{
"name": "network",
"in": "query",
"required": true,
"schema": {
"enum": [
"REGTEST",
"MAINNET"
],
"type": "string",
"title": "Network"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"default": 25,
"title": "Limit"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WalletLeaderboard"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/tokens/{identifier}": {
"get": {
"tags": [
"Tokens"
],
"summary": "Get Token Details by Pubkey or Search Tokens",
"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.",
"operationId": "get_token_info_by_identifier_v1_tokens__identifier__get",
"parameters": [
{
"name": "identifier",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Identifier"
}
},
{
"name": "network",
"in": "query",
"required": true,
"schema": {
"enum": [
"REGTEST",
"MAINNET"
],
"type": "string",
"title": "Network"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Limit for search results if identifier is a query string",
"default": 25,
"title": "Limit"
},
"description": "Limit for search results if identifier is a query string"
},
{
"name": "offset",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 0,
"description": "Offset for search results if identifier is a query string",
"default": 0,
"title": "Offset"
},
"description": "Offset for search results if identifier is a query string"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"$ref": "#/components/schemas/TokenDetailsResponse"
},
{
"type": "array",
"items": {
"$ref": "#/components/schemas/TokenMetadata"
}
}
],
"title": "Response Get Token Info By Identifier V1 Tokens Identifier Get"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/tokens/{identifier}/transactions": {
"get": {
"tags": [
"Tokens"
],
"summary": "Get Token Transactions",
"operationId": "get_token_transactions_v1_tokens__identifier__transactions_get",
"parameters": [
{
"name": "identifier",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Identifier"
}
},
{
"name": "network",
"in": "query",
"required": true,
"schema": {
"enum": [
"REGTEST",
"MAINNET"
],
"type": "string",
"title": "Network"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"default": 25,
"title": "Limit"
}
},
{
"name": "offset",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 0,
"default": 0,
"title": "Offset"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TokenTransactionsResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/tokens/{identifier}/holders": {
"get": {
"tags": [
"Tokens"
],
"summary": "Get Token Holders",
"operationId": "get_token_holders_v1_tokens__identifier__holders_get",
"parameters": [
{
"name": "identifier",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Identifier"
}
},
{
"name": "network",
"in": "query",
"required": true,
"schema": {
"enum": [
"REGTEST",
"MAINNET"
],
"type": "string",
"title": "Network"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"default": 25,
"title": "Limit"
}
},
{
"name": "offset",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 0,
"default": 0,
"title": "Offset"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TokenHoldersResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/address/{address}/tokens": {
"get": {
"tags": [
"Address"
],
"summary": "Get Address Tokens",
"operationId": "get_address_tokens_v1_address__address__tokens_get",
"parameters": [
{
"name": "address",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Address"
}
},
{
"name": "network",
"in": "query",
"required": true,
"schema": {
"enum": [
"REGTEST",
"MAINNET"
],
"type": "string",
"title": "Network"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AddressTokensResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/stats/leaderboard/tokens": {
"get": {
"tags": [
"Stats"
],
"summary": "Get Token Leaderboard",
"operationId": "get_token_leaderboard_v1_stats_leaderboard_tokens_get",
"parameters": [
{
"name": "network",
"in": "query",
"required": true,
"schema": {
"enum": [
"REGTEST",
"MAINNET"
],
"type": "string",
"title": "Network"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"default": 25,
"title": "Limit"
}
},
{
"name": "offset",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 0,
"default": 0,
"title": "Offset"
}
},
{
"name": "afterUpdatedAt",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "date-time",
"nullable": true
},
"description": "Return only tokens whose updatedAt timestamp is after the given ISO timestamp."
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TokenLeaderboardResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/tokens/metadata/batch": {
"post": {
"tags": [
"Tokens"
],
"summary": "Get Token Metadata in 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.",
"operationId": "get_batch_token_metadata_v1_tokens_metadata_batch_post",
"parameters": [
{
"name": "network",
"in": "query",
"required": true,
"schema": {
"enum": [
"REGTEST",
"MAINNET"
],
"type": "string",
"title": "Network"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BatchTokenMetadataRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BatchTokenMetadataResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/bitcoin/addresses/latest-txid": {
"post": {
"tags": [
"Bitcoin"
],
"summary": "Get Addresses Latest Txid",
"description": "Get the latest transaction ID for each Bitcoin address.\n\nArgs:\n addresses: List of Bitcoin addresses (max 100)\n network: Network to use (REGTEST or MAINNET)\n\nReturns:\n Dictionary mapping each address to its latest transaction ID (or null if no transactions)",
"operationId": "get_addresses_latest_txid_v1_bitcoin_addresses_latest_txid_post",
"parameters": [
{
"name": "network",
"in": "query",
"required": true,
"schema": {
"enum": [
"REGTEST",
"MAINNET"
],
"type": "string",
"title": "Network"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "string"
},
"title": "Addresses"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": {
"type": "string",
"nullable": true
},
"title": "Response Get Addresses Latest Txid V1 Bitcoin Addresses Latest Txid Post"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/tokens/issuer-lookup": {
"post": {
"tags": [
"Tokens"
],
"summary": "Lookup token ↔ issuer pubkey",
"description": "Convert issuer public keys to their token identifier/address or vice-versa. Accepts up to 100 items per request.",
"operationId": "token_issuer_lookup_v1_tokens_issuer_lookup_post",
"parameters": [
{
"name": "network",
"in": "query",
"required": true,
"schema": {
"enum": [
"REGTEST",
"MAINNET"
],
"type": "string",
"title": "Network"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TokenIssuerLookupRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TokenIssuerLookupResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"AddressSummaryResponse": {
"properties": {
"sparkAddress": {
"type": "string"
},
"publicKey": {
"type": "string"
},
"balance": {
"$ref": "#/components/schemas/BalanceSummary"
},
"totalValueUsd": {
"type": "number"
},
"transactionCount": {
"type": "integer"
},
"tokenCount": {
"type": "integer"
},
"tokens": {
"items": {
"$ref": "#/components/schemas/AddressToken"
},
"type": "array",
"nullable": true
}
},
"type": "object",
"required": [
"sparkAddress",
"publicKey",
"balance",
"totalValueUsd",
"transactionCount",
"tokenCount"
],
"title": "AddressSummaryResponse"
},
"AddressToken": {
"properties": {
"tokenIdentifier": {
"type": "string"
},
"tokenAddress": {
"type": "string"
},
"name": {
"type": "string"
},
"ticker": {
"type": "string"
},
"decimals": {
"type": "integer"
},
"balance": {
"type": "integer"
},
"valueUsd": {
"type": "number",
"format": "float"
},
"issuerPublicKey": {
"type": "string"
},
"maxSupply": {
"type": "integer",
"nullable": true
},
"isFreezable": {
"type": "boolean",
"nullable": true
}
},
"type": "object",
"required": [
"tokenIdentifier",
"tokenAddress",
"name",
"ticker",
"decimals",
"balance",
"valueUsd",
"issuerPublicKey"
],
"title": "AddressToken"
},
"AddressTokensResponse": {
"properties": {
"address": {
"type": "string"
},
"pubkey": {
"type": "string"
},
"totalValueUsd": {
"type": "number",
"format": "float"
},
"tokens": {
"items": {
"$ref": "#/components/schemas/AddressToken"
},
"type": "array"
}
},
"type": "object",
"required": [
"address",
"pubkey",
"totalValueUsd",
"tokens"
],
"title": "AddressTokensResponse"
},
"AddressTransaction": {
"properties": {
"id": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"spark_transfer",
"lightning_payment",
"bitcoin_deposit",
"bitcoin_withdrawal",
"token_transfer",
"token_mint",
"token_burn",
"token_multi_transfer",
"unknown_token_op"
]
},
"direction": {
"type": "string",
"enum": [
"incoming",
"outgoing",
"creation",
"destruction",
"transfer",
"deposit",
"withdrawal",
"payment",
"settlement",
"unknown"
]
},
"counterparty": {
"$ref": "#/components/schemas/TransactionCounterparty"
},
"amountSats": {
"type": "integer",
"nullable": true
},
"tokenAmount": {
"type": "integer",
"nullable": true
},
"valueUsd": {
"type": "number",
"format": "float"
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "When the transaction was first recorded/broadcast.",
"nullable": true
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Last update / completion timestamp.",
"nullable": true
},
"status": {
"type": "string",
"enum": [
"confirmed",
"pending",
"sent",
"failed",
"expired"
]
},
"txid": {
"type": "string",
"nullable": true
},
"tokenMetadata": {
"$ref": "#/components/schemas/TokenTransactionMetadata",
"nullable": true
},
"multiIoDetails": {
"$ref": "#/components/schemas/MultiIoDetails",
"description": "Details for multi-input/output transactions",
"nullable": true
}
},
"type": "object",
"required": [
"id",
"type",
"direction",
"counterparty",
"valueUsd",
"status"
],
"title": "AddressTransaction"
},
"AddressTransactionsResponse": {
"properties": {
"meta": {
"$ref": "#/components/schemas/TransactionMeta"
},
"data": {
"items": {
"$ref": "#/components/schemas/AddressTransaction"
},
"type": "array"
}
},
"type": "object",
"required": [
"meta",
"data"
],
"title": "AddressTransactionsResponse"
},
"BalanceSummary": {
"properties": {
"btcSoftBalanceSats": {
"type": "integer"
},
"btcHardBalanceSats": {
"type": "integer"
},
"btcValueUsdHard": {
"type": "number",
"format": "float"
},
"btcValueUsdSoft": {
"type": "number",
"format": "float"
},
"totalTokenValueUsd": {
"type": "number",
"format": "float"
}
},
"type": "object",
"required": [
"btcSoftBalanceSats",
"btcHardBalanceSats",
"btcValueUsdHard",
"btcValueUsdSoft",
"totalTokenValueUsd"
],
"title": "BalanceSummary"
},
"BatchTokenMetadataRequest": {
"properties": {
"token_addresses": {
"items": {
"type": "string",
"pattern": "^[0-9a-fA-F]{66}$"
},
"type": "array",
"maxItems": 100,
"minItems": 1,
"description": "List of 66-character hex token addresses"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"token_addresses"
],
"title": "BatchTokenMetadataRequest",
"description": "Request schema for batch token metadata lookup"
},
"BatchTokenMetadataResponse": {
"properties": {
"metadata": {
"items": {
"$ref": "#/components/schemas/TokenMetadata"
},
"type": "array",
"description": "List of token metadata objects"
},
"total_count": {
"type": "integer",
"description": "Total number of tokens processed"
}
},
"type": "object",
"required": [
"metadata",
"total_count"
],
"title": "BatchTokenMetadataResponse",
"description": "Response schema for batch token metadata lookup"
},
"BitcoinTxDetails": {
"properties": {
"txid": {
"type": "string",
"title": "Txid"
},
"vin": {
"items": {
"$ref": "#/components/schemas/TxVin"
},
"type": "array",
"title": "Vin"
},
"vout": {
"items": {
"$ref": "#/components/schemas/TxVout"
},
"type": "array",
"title": "Vout"
},
"status": {
"$ref": "#/components/schemas/TxStatus"
},
"fee": {
"type": "integer",
"title": "Fee"
}
},
"type": "object",
"required": [
"txid",
"vin",
"vout",
"status",
"fee"
],
"title": "BitcoinTxDetails"
},
"HTTPValidationError": {
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
},
"HistoricalDataPoint": {
"properties": {
"timestamp": {
"type": "string",
"format": "date-time"
},
"value": {
"type": "integer"
}
},
"type": "object",
"required": [
"timestamp",
"value"
],
"title": "HistoricalDataPoint"
},
"HistoricalTpvResponse": {
"properties": {
"network": {
"type": "string",
"enum": [
"REGTEST",
"MAINNET"
]
},
"start_date": {
"type": "string",
"format": "date"
},
"end_date": {
"type": "string",
"format": "date"
},
"granularity": {
"type": "string",
"enum": [
"daily",
"weekly"
]
},
"data": {
"items": {
"$ref": "#/components/schemas/HistoricalDataPoint"
},
"type": "array"
}
},
"type": "object",
"required": [
"network",
"start_date",
"end_date",
"granularity",
"data"
],
"title": "HistoricalTpvResponse"
},
"HistoricalTvlResponse": {
"properties": {
"network": {
"type": "string",
"enum": [
"REGTEST",
"MAINNET"
]
},
"start_date": {
"type": "string",
"format": "date"
},
"end_date": {
"type": "string",
"format": "date"
},
"granularity": {
"type": "string",
"enum": [
"daily",
"weekly"
]
},
"data": {
"items": {
"$ref": "#/components/schemas/HistoricalDataPoint"
},
"type": "array"
}
},
"type": "object",
"required": [
"network",
"start_date",
"end_date",
"granularity",
"data"
],
"title": "HistoricalTvlResponse"
},
"HistoricalWalletsResponse": {
"properties": {
"network": {
"type": "string",
"enum": [
"REGTEST",
"MAINNET"
]
},
"start_date": {
"type": "string",
"format": "date"
},
"end_date": {
"type": "string",
"format": "date"
},
"granularity": {
"type": "string",
"enum": [
"daily",
"weekly"
]
},
"data": {
"items": {
"$ref": "#/components/schemas/HistoricalDataPoint"
},
"type": "array"
}
},
"type": "object",
"required": [
"network",
"start_date",
"end_date",
"granularity",
"data"
],
"title": "HistoricalWalletsResponse"
},
"LatestNetworkTransactionItem": {
"properties": {
"id": {
"type": "string",
"description": "Transaction ID (UUID for Spark/LN, hash for BTC/Token)"
},
"type": {
"type": "string",
"enum": [
"bitcoin_deposit",
"bitcoin_withdrawal",
"spark_transfer",
"lightning_payment",
"token_mint",
"token_transfer",
"token_burn",
"token_multi_transfer",
"unknown_token_op",
"unknown_transfer"
]
},
"status": {
"type": "string",
"enum": [
"confirmed",
"pending",
"sent",
"failed",
"expired"
]
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "When the transaction was first recorded/broadcast.",
"nullable": true
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Last update / completion timestamp.",
"nullable": true
},
"amountSats": {
"type": "integer",
"nullable": true
},
"tokenAmount": {
"type": "integer",
"nullable": true
},
"tokenMetadata": {
"$ref": "#/components/schemas/TokenTransactionMetadata",
"nullable": true
},
"multiIoDetails": {
"$ref": "#/components/schemas/MultiIoDetails",
"description": "Details for multi-input/output transactions",
"nullable": true
},
"from": {
"$ref": "#/components/schemas/TransactionParty",
"nullable": true
},
"to": {
"$ref": "#/components/schemas/TransactionParty",
"nullable": true
},
"bitcoinTxid": {
"type": "string",
"nullable": true
},
"valueUsd": {
"type": "number",
"format": "float"
}
},
"type": "object",
"required": [
"id",
"type",
"status",
"valueUsd"
],
"title": "LatestNetworkTransactionItem"
},
"MultiIoDetails": {
"properties": {
"inputs": {
"items": {
"$ref": "#/components/schemas/TokenIoDetail"
},
"type": "array",
"description": "List of input addresses and amounts"
},
"outputs": {
"items": {
"$ref": "#/components/schemas/TokenIoDetail"
},
"type": "array",
"description": "List of output addresses and amounts"
},
"totalInputAmount": {
"type": "integer",
"description": "Sum of all input amounts"
},
"totalOutputAmount": {
"type": "integer",
"description": "Sum of all output amounts"
}
},
"type": "object",
"required": [
"inputs",
"outputs",
"totalInputAmount",
"totalOutputAmount"
],
"title": "MultiIoDetails"
},
"NetworkStats": {
"properties": {
"totalValueLockedSats": {
"type": "integer",
"title": "Totalvaluelockedsats"
},
"totalValueLockedUsd": {
"type": "number",
"title": "Totalvaluelockedusd"
},
"activeAccounts": {
"type": "integer",
"title": "Activeaccounts"
},
"transactions24h": {
"type": "integer",
"title": "Transactions24H"
},
"currentBtcPriceUsd": {
"type": "number",
"title": "Currentbtcpriceusd"
}
},
"type": "object",
"required": [
"totalValueLockedSats",
"totalValueLockedUsd",
"activeAccounts",
"transactions24h",
"currentBtcPriceUsd"
],
"title": "NetworkStats"
},
"PeriodTpvStats": {
"properties": {
"period": {
"$ref": "#/components/schemas/TpvPeriod"
},
"tpvSats": {
"type": "integer",
"title": "Tpvsats"
},
"tpvUsd": {
"type": "number",
"title": "Tpvusd"
},
"startTime": {
"type": "string",
"format": "date-time",
"title": "Starttime"
},
"endTime": {
"type": "string",
"format": "date-time",
"title": "Endtime"
}
},
"type": "object",
"required": [
"period",
"tpvSats",
"tpvUsd",
"startTime",
"endTime"
],
"title": "PeriodTpvStats"
},
"TokenDetailsResponse": {
"properties": {
"metadata": {
"$ref": "#/components/schemas/TokenMetadata"
},
"totalSupply": {
"type": "integer"
},
"marketCapUsd": {
"type": "number",
"format": "float"
},
"volume24hUsd": {
"type": "number",
"format": "float"
}
},
"type": "object",
"required": [
"metadata",
"totalSupply",
"marketCapUsd",
"volume24hUsd"
],
"title": "TokenDetailsResponse"
},
"TokenHolder": {
"properties": {
"address": {
"type": "string"
},
"pubkey": {
"type": "string"
},
"balance": {
"type": "integer"
},
"valueUsd": {
"type": "number",
"format": "float"
},
"percentage": {
"type": "number",
"format": "float"
}
},
"type": "object",
"required": [
"address",
"pubkey",
"balance",
"valueUsd",
"percentage"
],
"title": "TokenHolder"
},
"TokenHoldersResponse": {
"properties": {
"meta": {
"$ref": "#/components/schemas/TransactionMeta"
},
"data": {
"items": {
"$ref": "#/components/schemas/TokenHolder"
},
"type": "array"
}
},
"type": "object",
"required": [
"meta",
"data"
],
"title": "TokenHoldersResponse"
},
"TokenIoDetail": {
"properties": {
"address": {
"type": "string",
"description": "Spark address"
},
"pubkey": {
"type": "string",
"description": "Public key in hex"
},
"amount": {
"type": "integer",
"description": "Token amount"
}
},
"type": "object",
"required": [
"address",
"pubkey",
"amount"
],
"title": "TokenIoDetail"
},
"TokenIssuerLookupItem": {
"properties": {
"pubkey": {
"type": "string",
"nullable": true
},
"tokenIdentifier": {
"type": "string",
"nullable": true
},
"tokenAddress": {
"type": "string",
"nullable": true
}
},
"type": "object",
"title": "TokenIssuerLookupItem"
},
"TokenIssuerLookupRequest": {
"properties": {
"pubkeys": {
"items": {
"type": "string"
},
"type": "array",
"maxItems": 100,
"nullable": true
},
"tokens": {
"items": {
"type": "string"
},
"type": "array",
"maxItems": 100,
"nullable": true
}
},
"type": "object",
"title": "TokenIssuerLookupRequest"
},
"TokenIssuerLookupResponse": {
"properties": {
"results": {
"items": {
"$ref": "#/components/schemas/TokenIssuerLookupItem"
},
"type": "array",
"title": "Results"
}
},
"type": "object",
"required": [
"results"
],
"title": "TokenIssuerLookupResponse"
},
"TokenLeaderboardEntry": {
"properties": {
"rank": {
"type": "integer"
},
"tokenIdentifier": {
"type": "string"
},
"tokenAddress": {
"type": "string"
},
"issuerPublicKey": {
"type": "string"
},
"name": {
"type": "string"
},
"ticker": {
"type": "string"
},
"decimals": {
"type": "integer"
},
"iconUrl": {
"type": "string"
},
"holderCount": {
"type": "integer"
},
"priceUsd": {
"type": "number",
"format": "float"
},
"totalSupply": {
"type": "integer"
},
"marketCapUsd": {
"type": "number",
"format": "float"
},
"volume24hUsd": {
"type": "number",
"format": "float"
},
"maxSupply": {
"type": "integer",
"nullable": true
},
"isFreezable": {
"type": "boolean",
"nullable": true
},
"createdAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"updatedAt": {
"type": "string",
"format": "date-time",
"nullable": true
}
},
"type": "object",
"required": [
"rank",
"tokenIdentifier",
"tokenAddress",
"issuerPublicKey",
"name",
"ticker",
"decimals",
"iconUrl",
"holderCount",
"priceUsd",
"totalSupply",
"marketCapUsd",
"volume24hUsd"
],
"title": "TokenLeaderboardEntry"
},
"TokenLeaderboardResponse": {
"properties": {
"totalTokens": {
"type": "integer"
},
"leaderboard": {
"items": {
"$ref": "#/components/schemas/TokenLeaderboardEntry"
},
"type": "array"
}
},
"type": "object",
"required": [
"totalTokens",
"leaderboard"
],
"title": "TokenLeaderboardResponse"
},
"TokenMetadata": {
"properties": {
"tokenIdentifier": {
"type": "string"
},
"tokenAddress": {
"type": "string"
},
"name": {
"type": "string"
},
"ticker": {
"type": "string"
},
"decimals": {
"type": "integer"
},
"issuerPublicKey": {
"type": "string"
},
"iconUrl": {
"type": "string"
},
"holderCount": {
"type": "integer"
},
"priceUsd": {
"type": "number",
"format": "float"
},
"maxSupply": {
"type": "integer",
"nullable": true
},
"isFreezable": {
"type": "boolean",
"nullable": true
},
"createdAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"updatedAt": {
"type": "string",
"format": "date-time",
"nullable": true
}
},
"type": "object",
"required": [
"tokenIdentifier",
"tokenAddress",
"name",
"ticker",
"decimals",
"issuerPublicKey",
"iconUrl",
"holderCount",
"priceUsd"
],
"title": "TokenMetadata"
},
"TokenTransaction": {
"properties": {
"id": {
"type": "string"
},
"type": {
"type": "string",
"description": "Transaction type",
"example": "token_transfer"
},
"status": {
"type": "string",
"enum": [
"confirmed",
"pending",
"sent",
"failed",
"expired"
]
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "When the transaction was first created/broadcast.",
"nullable": true
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Last update / completion timestamp.",
"nullable": true
},
"from": {
"$ref": "#/components/schemas/TransactionParty",
"description": "Sender information. May be null for multi-output transactions.",
"nullable": true
},
"to": {
"$ref": "#/components/schemas/TransactionParty",
"description": "Receiver information. May be null for multi-output transactions.",
"nullable": true
},
"amount": {
"type": "integer",
"description": "Total output amount for the transaction"
},
"valueUsd": {
"type": "number",
"format": "float"
},
"tokenMetadata": {
"$ref": "#/components/schemas/TokenTransactionMetadata"
},
"multiIoDetails": {
"$ref": "#/components/schemas/MultiIoDetails",
"description": "Details for multi-input/output transactions",
"nullable": true
}
},
"type": "object",
"required": [
"id",
"type",
"status",
"amount",
"valueUsd",
"tokenMetadata"
],
"title": "TokenTransaction"
},
"TokenTransactionMetadata": {
"properties": {
"tokenIdentifier": {
"type": "string"
},
"tokenAddress": {
"type": "string"
},
"name": {
"type": "string"
},
"ticker": {
"type": "string"
},
"decimals": {
"type": "integer"
},
"issuerPublicKey": {
"type": "string"
},
"maxSupply": {
"type": "integer",
"nullable": true
},
"isFreezable": {
"type": "boolean",
"nullable": true
}
},
"type": "object",
"required": [
"tokenIdentifier",
"tokenAddress",
"name",
"ticker",
"decimals",
"issuerPublicKey"
],
"title": "TokenTransactionMetadata"
},
"TokenTransactionsResponse": {
"properties": {
"meta": {
"$ref": "#/components/schemas/TransactionMeta"
},
"data": {
"items": {
"$ref": "#/components/schemas/TokenTransaction"
},
"type": "array"
}
},
"type": "object",
"required": [
"meta",
"data"
],
"title": "TokenTransactionsResponse"
},
"TpvPeriod": {
"type": "string",
"enum": [
"24h",
"7d",
"30d",
"all"
],
"title": "TpvPeriod"
},
"TransactionCounterparty": {
"properties": {
"type": {
"type": "string",
"enum": [
"spark",
"lightning",
"bitcoin",
"token"
]
},
"identifier": {
"type": "string"
},
"tokenMetadata": {
"$ref": "#/components/schemas/TokenTransactionMetadata",
"nullable": true
}
},
"type": "object",
"required": [
"type",
"identifier"
],
"title": "TransactionCounterparty"
},
"TransactionMeta": {
"properties": {
"totalItems": {
"type": "integer"
},
"limit": {
"type": "integer"
},
"offset": {
"type": "integer"
}
},
"type": "object",
"required": [
"totalItems",
"limit",
"offset"
],
"title": "TransactionMeta"
},
"TransactionParty": {
"properties": {
"type": {
"type": "string",
"enum": [
"spark",
"lightning",
"bitcoin",
"issuer",
"burn_address",
"unknown"
]
},
"identifier": {
"type": "string"
},
"pubkey": {
"type": "string",
"nullable": true
}
},
"type": "object",
"required": [
"type",
"identifier"
],
"title": "TransactionParty"
},
"TxStatus": {
"properties": {
"confirmed": {
"type": "boolean"
},
"block_height": {
"nullable": true
},
"block_time": {
"nullable": true
}
},
"type": "object",
"required": [
"confirmed"
],
"title": "TxStatus"
},
"TxV1Response": {
"properties": {
"id": {
"type": "string"
},
"type": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"confirmed",
"pending",
"sent",
"failed",
"expired"
]
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "When the transaction was first recorded/initiated.",
"nullable": true
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Last update / completion timestamp.",
"nullable": true
},
"from": {
"$ref": "#/components/schemas/TransactionParty",
"nullable": true
},
"to": {
"$ref": "#/components/schemas/TransactionParty",
"nullable": true
},
"amountSats": {
"type": "integer"
},
"valueUsd": {
"type": "number",
"format": "float"
},
"timeTakenSeconds": {
"type": "number",
"format": "float",
"description": "Duration of the transaction in seconds (from creation to completion). Null if start time is unavailable.",
"nullable": true
},
"txid": {
"type": "string",
"nullable": true
},
"bitcoinTxData": {
"$ref": "#/components/schemas/BitcoinTxDetails",
"nullable": true
}
},
"type": "object",
"required": [
"id",
"type",
"status",
"amountSats",
"valueUsd"
],
"title": "TxV1Response"
},
"TxVin": {
"properties": {
"prevout": {
"nullable": true
},
"witness": {
"nullable": true
},
"value": {
"type": "integer"
}
},
"type": "object",
"title": "TxVin"
},
"TxVout": {
"properties": {
"scriptpubkey_address": {
"nullable": true
},
"value": {
"type": "integer"
}
},
"type": "object",
"required": [
"value"
],
"title": "TxVout"
},
"ValidationError": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"WalletLeaderboard": {
"properties": {
"leaderboard": {
"items": {
"$ref": "#/components/schemas/WalletLeaderboardEntry"
},
"type": "array",
"title": "Leaderboard"
},
"currentBtcPriceUsd": {
"type": "number",
"title": "Currentbtcpriceusd",
"default": 0.0
}
},
"type": "object",
"required": [
"leaderboard"
],
"title": "WalletLeaderboard"
},
"WalletLeaderboardEntry": {
"properties": {
"rank": {
"type": "integer",
"title": "Rank"
},
"sparkAddress": {
"type": "string",
"title": "Sparkaddress"
},
"pubkey": {
"type": "string",
"title": "Pubkey"
},
"totalValueSats": {
"type": "integer",
"title": "Totalvaluesats"
},
"totalValueUsd": {
"type": "number",
"title": "Totalvalueusd",
"default": 0.0
}
},
"type": "object",
"required": [
"rank",
"sparkAddress",
"pubkey",
"totalValueSats"
],
"title": "WalletLeaderboardEntry"
}
}
},
"tags": [
{
"name": "Address",
"description": "Operations related to addresses"
},
{
"name": "Tx",
"description": "Operations related to transactions"
},
{
"name": "Stats",
"description": "Network statistics and leaderboards"
},
{
"name": "Tokens",
"description": "Operations related to tokens"
}
]
}