BlockQuery ← Back to setup

MCP catalogue

BlockQuery MCP tools

Live tool surface for Bitcoin chain lookups, risk scoring, credits, and Lightning payment flow. Prefer batch tools ending in _multi when screening many ids.

Tools

28

Endpoint

https://blockquery-testnet.chainprint.tech/mcp

Auth

Bearer token

Chainspector (20)

address_exists_multi

Batch chainspect `address_exists_multi`: look up many Bitcoin addresses in one call. Pass as many Bitcoin addresses as you can in one call — prefer a single large batch over many small calls; do not loop this per item. Args: addresses: List of Bitcoin addresses. Returns: One result per input, in the same order.

argumenttyperequireddescription
addressesarray<string>yes

Returns: array<boolean>

output schema
{
  "properties": {
    "result": {
      "items": {
        "type": "boolean"
      },
      "title": "Result",
      "type": "array"
    }
  },
  "required": [
    "result"
  ],
  "title": "address_exists_multiOutput",
  "type": "object"
}

address_output_count_multi

Batch chainspect `address_output_count_multi`: look up many Bitcoin addresses in one call. Pass as many Bitcoin addresses as you can in one call — prefer a single large batch over many small calls; do not loop this per item. Args: addresses: List of Bitcoin addresses. Returns: One result per input, in the same order.

argumenttyperequireddescription
addressesarray<string>yes

Returns: array<integer>

output schema
{
  "properties": {
    "result": {
      "items": {
        "type": "integer"
      },
      "title": "Result",
      "type": "array"
    }
  },
  "required": [
    "result"
  ],
  "title": "address_output_count_multiOutput",
  "type": "object"
}

address_outputs_multi

Batch chainspect `address_outputs_multi`: look up many Bitcoin addresses in one call. Pass as many Bitcoin addresses as you can in one call — prefer a single large batch over many small calls; do not loop this per item. Args: addresses: List of Bitcoin addresses. Returns: One result per input, in the same order.

argumenttyperequireddescription
addressesarray<string>yes

Returns: array<array<string>>

output schema
{
  "properties": {
    "result": {
      "items": {
        "items": {
          "type": "string"
        },
        "type": "array"
      },
      "title": "Result",
      "type": "array"
    }
  },
  "required": [
    "result"
  ],
  "title": "address_outputs_multiOutput",
  "type": "object"
}

block_height_txs_multi

Batch chainspect `block_height_txs_multi`: look up many block heights in one call. Pass as many block heights as you can in one call — prefer a single large batch over many small calls; do not loop this per item. Args: block_heights: List of block heights. Returns: One result per input, in the same order.

argumenttyperequireddescription
block_heightsarray<integer>yes

Returns: array<array<string>>

output schema
{
  "properties": {
    "result": {
      "items": {
        "items": {
          "type": "string"
        },
        "type": "array"
      },
      "title": "Result",
      "type": "array"
    }
  },
  "required": [
    "result"
  ],
  "title": "block_height_txs_multiOutput",
  "type": "object"
}

latest_block

Return the height of the latest Bitcoin block processed by chainspect. Returns: The block height (e.g. 801387) of the most recently processed block.

No arguments.

Returns: integer

output schema
{
  "properties": {
    "result": {
      "title": "Result",
      "type": "integer"
    }
  },
  "required": [
    "result"
  ],
  "title": "latest_blockOutput",
  "type": "object"
}

output_address_multi

Batch chainspect `output_address_multi`: look up many output ids (<txid>_<n>) in one call. Pass as many output ids (<txid>_<n>) as you can in one call — prefer a single large batch over many small calls; do not loop this per item. Args: outputs: List of output ids (<txid>_<n>). Returns: One result per input, in the same order.

argumenttyperequireddescription
outputsarray<string>yes

Returns: array<string | null>

output schema
{
  "properties": {
    "result": {
      "items": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ]
      },
      "title": "Result",
      "type": "array"
    }
  },
  "required": [
    "result"
  ],
  "title": "output_address_multiOutput",
  "type": "object"
}

output_exists_multi

Batch chainspect `output_exists_multi`: look up many output ids (<txid>_<n>) in one call. Pass as many output ids (<txid>_<n>) as you can in one call — prefer a single large batch over many small calls; do not loop this per item. Args: outputs: List of output ids (<txid>_<n>). Returns: One result per input, in the same order.

argumenttyperequireddescription
outputsarray<string>yes

Returns: array<boolean>

output schema
{
  "properties": {
    "result": {
      "items": {
        "type": "boolean"
      },
      "title": "Result",
      "type": "array"
    }
  },
  "required": [
    "result"
  ],
  "title": "output_exists_multiOutput",
  "type": "object"
}

output_next_tx_multi

Batch chainspect `output_next_tx_multi`: look up many output ids (<txid>_<n>) in one call. Pass as many output ids (<txid>_<n>) as you can in one call — prefer a single large batch over many small calls; do not loop this per item. Args: outputs: List of output ids (<txid>_<n>). Returns: One result per input, in the same order.

argumenttyperequireddescription
outputsarray<string>yes

Returns: array<array<string>>

output schema
{
  "properties": {
    "result": {
      "items": {
        "items": {
          "type": "string"
        },
        "type": "array"
      },
      "title": "Result",
      "type": "array"
    }
  },
  "required": [
    "result"
  ],
  "title": "output_next_tx_multiOutput",
  "type": "object"
}

output_script_type_multi

Batch chainspect `output_script_type_multi`: look up many output ids (<txid>_<n>) in one call. Pass as many output ids (<txid>_<n>) as you can in one call — prefer a single large batch over many small calls; do not loop this per item. Args: outputs: List of output ids (<txid>_<n>). Returns: One result per input, in the same order.

argumenttyperequireddescription
outputsarray<string>yes

Returns: array<string>

output schema
{
  "properties": {
    "result": {
      "items": {
        "type": "string"
      },
      "title": "Result",
      "type": "array"
    }
  },
  "required": [
    "result"
  ],
  "title": "output_script_type_multiOutput",
  "type": "object"
}

output_tx_multi

Batch chainspect `output_tx_multi`: look up many output ids (<txid>_<n>) in one call. Pass as many output ids (<txid>_<n>) as you can in one call — prefer a single large batch over many small calls; do not loop this per item. Args: outputs: List of output ids (<txid>_<n>). Returns: One result per input, in the same order.

argumenttyperequireddescription
outputsarray<string>yes

Returns: array<string>

output schema
{
  "properties": {
    "result": {
      "items": {
        "type": "string"
      },
      "title": "Result",
      "type": "array"
    }
  },
  "required": [
    "result"
  ],
  "title": "output_tx_multiOutput",
  "type": "object"
}

output_value_multi

Batch chainspect `output_value_multi`: look up many output ids (<txid>_<n>) in one call. Pass as many output ids (<txid>_<n>) as you can in one call — prefer a single large batch over many small calls; do not loop this per item. Args: outputs: List of output ids (<txid>_<n>). Returns: One result per input, in the same order.

argumenttyperequireddescription
outputsarray<string>yes

Returns: array<integer>

output schema
{
  "properties": {
    "result": {
      "items": {
        "type": "integer"
      },
      "title": "Result",
      "type": "array"
    }
  },
  "required": [
    "result"
  ],
  "title": "output_value_multiOutput",
  "type": "object"
}

tx_block_height_multi

Batch chainspect `tx_block_height_multi`: look up many transaction ids in one call. Pass as many transaction ids as you can in one call — prefer a single large batch over many small calls; do not loop this per item. Args: txs: List of transaction ids. Returns: One result per input, in the same order.

argumenttyperequireddescription
txsarray<string>yes

Returns: array<integer>

output schema
{
  "properties": {
    "result": {
      "items": {
        "type": "integer"
      },
      "title": "Result",
      "type": "array"
    }
  },
  "required": [
    "result"
  ],
  "title": "tx_block_height_multiOutput",
  "type": "object"
}

tx_exists_multi

Batch chainspect `tx_exists_multi`: look up many transaction ids in one call. Pass as many transaction ids as you can in one call — prefer a single large batch over many small calls; do not loop this per item. Args: txs: List of transaction ids. Returns: One result per input, in the same order.

argumenttyperequireddescription
txsarray<string>yes

Returns: array<boolean>

output schema
{
  "properties": {
    "result": {
      "items": {
        "type": "boolean"
      },
      "title": "Result",
      "type": "array"
    }
  },
  "required": [
    "result"
  ],
  "title": "tx_exists_multiOutput",
  "type": "object"
}

tx_input_count_multi

Batch chainspect `tx_input_count_multi`: look up many transaction ids in one call. Pass as many transaction ids as you can in one call — prefer a single large batch over many small calls; do not loop this per item. Args: txs: List of transaction ids. Returns: One result per input, in the same order.

argumenttyperequireddescription
txsarray<string>yes

Returns: array<integer>

output schema
{
  "properties": {
    "result": {
      "items": {
        "type": "integer"
      },
      "title": "Result",
      "type": "array"
    }
  },
  "required": [
    "result"
  ],
  "title": "tx_input_count_multiOutput",
  "type": "object"
}

tx_inputs_multi

Batch chainspect `tx_inputs_multi`: look up many transaction ids in one call. Pass as many transaction ids as you can in one call — prefer a single large batch over many small calls; do not loop this per item. Args: txs: List of transaction ids. Returns: One result per input, in the same order.

argumenttyperequireddescription
txsarray<string>yes

Returns: array<array<string>>

output schema
{
  "properties": {
    "result": {
      "items": {
        "items": {
          "type": "string"
        },
        "type": "array"
      },
      "title": "Result",
      "type": "array"
    }
  },
  "required": [
    "result"
  ],
  "title": "tx_inputs_multiOutput",
  "type": "object"
}

tx_locktime_multi

Batch chainspect `tx_locktime_multi`: look up many transaction ids in one call. Pass as many transaction ids as you can in one call — prefer a single large batch over many small calls; do not loop this per item. Args: txs: List of transaction ids. Returns: One result per input, in the same order.

argumenttyperequireddescription
txsarray<string>yes

Returns: array<integer>

output schema
{
  "properties": {
    "result": {
      "items": {
        "type": "integer"
      },
      "title": "Result",
      "type": "array"
    }
  },
  "required": [
    "result"
  ],
  "title": "tx_locktime_multiOutput",
  "type": "object"
}

tx_mined_timestamp_multi

Batch chainspect `tx_mined_timestamp_multi`: look up many transaction ids in one call. Pass as many transaction ids as you can in one call — prefer a single large batch over many small calls; do not loop this per item. Args: txs: List of transaction ids. Returns: One result per input, in the same order.

argumenttyperequireddescription
txsarray<string>yes

Returns: array<integer>

output schema
{
  "properties": {
    "result": {
      "items": {
        "type": "integer"
      },
      "title": "Result",
      "type": "array"
    }
  },
  "required": [
    "result"
  ],
  "title": "tx_mined_timestamp_multiOutput",
  "type": "object"
}

tx_output_count_multi

Batch chainspect `tx_output_count_multi`: look up many transaction ids in one call. Pass as many transaction ids as you can in one call — prefer a single large batch over many small calls; do not loop this per item. Args: txs: List of transaction ids. Returns: One result per input, in the same order.

argumenttyperequireddescription
txsarray<string>yes

Returns: array<integer>

output schema
{
  "properties": {
    "result": {
      "items": {
        "type": "integer"
      },
      "title": "Result",
      "type": "array"
    }
  },
  "required": [
    "result"
  ],
  "title": "tx_output_count_multiOutput",
  "type": "object"
}

tx_outputs_multi

Batch chainspect `tx_outputs_multi`: look up many transaction ids in one call. Pass as many transaction ids as you can in one call — prefer a single large batch over many small calls; do not loop this per item. Args: txs: List of transaction ids. Returns: One result per input, in the same order.

argumenttyperequireddescription
txsarray<string>yes

Returns: array<array<string>>

output schema
{
  "properties": {
    "result": {
      "items": {
        "items": {
          "type": "string"
        },
        "type": "array"
      },
      "title": "Result",
      "type": "array"
    }
  },
  "required": [
    "result"
  ],
  "title": "tx_outputs_multiOutput",
  "type": "object"
}

tx_vsize_multi

Batch chainspect `tx_vsize_multi`: look up many transaction ids in one call. Pass as many transaction ids as you can in one call — prefer a single large batch over many small calls; do not loop this per item. Args: txs: List of transaction ids. Returns: One result per input, in the same order.

argumenttyperequireddescription
txsarray<string>yes

Returns: array<integer>

output schema
{
  "properties": {
    "result": {
      "items": {
        "type": "integer"
      },
      "title": "Result",
      "type": "array"
    }
  },
  "required": [
    "result"
  ],
  "title": "tx_vsize_multiOutput",
  "type": "object"
}

Labelshub (1)

btc_usd_multi

Batch BTC/USD lookup: price labels per block height. Reads the `blockheight_btcusd_clovrlabs` labelshub dataset. Consumes 1 credit from the authenticated bearer token. Args: block_heights: List of Bitcoin block heights. Returns: One list of label payloads per input block height, in the same order.

argumenttyperequireddescription
block_heightsarray<integer>yes

Returns: array<array<object>>

output schema
{
  "properties": {
    "result": {
      "items": {
        "items": {
          "additionalProperties": true,
          "type": "object"
        },
        "type": "array"
      },
      "title": "Result",
      "type": "array"
    }
  },
  "required": [
    "result"
  ],
  "title": "btc_usd_multiOutput",
  "type": "object"
}

Pingu gRPC algorithms (2)

address_funds

Trace clustered funds for an address (pingu gRPC `AddressFunds`). Consumes 1 credit from the authenticated bearer token. Args: address: Bitcoin address. threshold: Minimum fund fraction to include (0-1). direction: "SOF" (source of funds) or "DOF" (destination of funds). max_block_height: Optional cap on the block height considered. Returns: Traced funds grouped by entity (amounts, share, and hop range).

argumenttyperequireddescription
addressstringyes
thresholdnumberyes
directionstringno
max_block_heightinteger | nullno

Returns: ClusterFunds

output schema
{
  "$defs": {
    "Amount": {
      "description": "A fund amount. Values are 4-decimal-rounded so fractional shares survive.",
      "properties": {
        "satoshis": {
          "default": 0.0,
          "description": "Amount in satoshis (fractional).",
          "title": "Satoshis",
          "type": "number"
        },
        "usd_cents": {
          "default": 0.0,
          "description": "Amount in USD cents.",
          "title": "Usd Cents",
          "type": "number"
        }
      },
      "title": "Amount",
      "type": "object"
    },
    "EntityFunds": {
      "description": "Funds attributed to a single entity.",
      "properties": {
        "name": {
          "default": "",
          "description": "Entity name.",
          "title": "Name",
          "type": "string"
        },
        "category": {
          "default": "",
          "description": "Entity category.",
          "title": "Category",
          "type": "string"
        },
        "amount": {
          "$ref": "#/$defs/Amount",
          "description": "Funds attributed to the entity."
        },
        "percentage": {
          "default": 0.0,
          "description": "Share of the total traced funds (0-1).",
          "title": "Percentage",
          "type": "number"
        },
        "hops": {
          "$ref": "#/$defs/HopRange",
          "description": "Hop-count range to the entity."
        }
      },
      "title": "EntityFunds",
      "type": "object"
    },
    "HopRange": {
      "description": "Inclusive range of hop counts between the address and the entity.",
      "properties": {
        "min": {
          "default": 0,
          "description": "Fewest hops.",
          "title": "Min",
          "type": "integer"
        },
        "max": {
          "default": 0,
          "description": "Most hops.",
          "title": "Max",
          "type": "integer"
        }
      },
      "title": "HopRange",
      "type": "object"
    }
  },
  "description": "Funds traced to/from an address, grouped by entity id.",
  "properties": {
    "entities": {
      "additionalProperties": {
        "$ref": "#/$defs/EntityFunds"
      },
      "description": "Entity id -> attributed funds.",
      "title": "Entities",
      "type": "object"
    }
  },
  "title": "ClusterFunds",
  "type": "object"
}

address_volume

Total in/out volume for an address (pingu gRPC `AddressVolume`). Args: address: Bitcoin address. Returns: Received (source) and sent (destination) volume in satoshis and USD.

argumenttyperequireddescription
addressstringyes

Returns: AddressVolume

output schema
{
  "$defs": {
    "VolumeAmount": {
      "description": "A volume figure in both satoshis and USD.",
      "properties": {
        "satoshis": {
          "default": 0,
          "description": "Amount in satoshis.",
          "title": "Satoshis",
          "type": "integer"
        },
        "usd": {
          "default": 0.0,
          "description": "Amount in USD.",
          "title": "Usd",
          "type": "number"
        }
      },
      "title": "VolumeAmount",
      "type": "object"
    }
  },
  "description": "Total volume flowing into (source) and out of (destination) an address.",
  "properties": {
    "source": {
      "$ref": "#/$defs/VolumeAmount",
      "description": "Received (source) volume."
    },
    "destination": {
      "$ref": "#/$defs/VolumeAmount",
      "description": "Sent (destination) volume."
    },
    "max_block_height": {
      "default": 0,
      "description": "Highest block height considered for the result.",
      "title": "Max Block Height",
      "type": "integer"
    }
  },
  "title": "AddressVolume",
  "type": "object"
}

ScoreMyCrypto risk scoring (2)

score_address

Risk-score a Bitcoin address with ScoreMyCrypto. Runs a full address risk assessment: an overall `risk_score`, a source- and destination-of-funds breakdown by entity category, counterparty identification, and a blacklist flag. Args: address: Bitcoin address to analyze. ai_confidence_threshold: Enable AI-inferred labels at this minimum confidence ("low", "medium", "high"). Omit to disable AI analysis. Returns: A terminal risk job. When `state` is "COMPLETED" the `result` field holds the address risk result. `state` "FAILED" is terminal (see `error_message`); "ValueError: address not found" means the address has no on-chain history. If the job is still pending after SCOREMYCRYPTO_MAX_WAIT, the tool times out and the reserved credit is refunded.

argumenttyperequireddescription
addressstringyes
ai_confidence_thresholdstring | nullno

Returns: AddressRiskJob

output schema
{
  "$defs": {
    "AIConfidence": {
      "description": "Categorical confidence level of an AI/ML prediction.",
      "enum": [
        "LOW",
        "MED",
        "HIGH"
      ],
      "title": "AIConfidence",
      "type": "string"
    },
    "AddressBalance": {
      "description": "Current address balance.",
      "properties": {
        "balance_sats": {
          "default": 0,
          "description": "Balance in satoshis.",
          "title": "Balance Sats",
          "type": "integer"
        },
        "balance_usd": {
          "default": 0.0,
          "description": "Balance in USD.",
          "title": "Balance Usd",
          "type": "number"
        }
      },
      "title": "AddressBalance",
      "type": "object"
    },
    "AddressRiskResult": {
      "description": "Risk assessment of a Bitcoin address.",
      "properties": {
        "risk_score": {
          "default": 0.0,
          "description": "Overall risk score.",
          "title": "Risk Score",
          "type": "number"
        },
        "address": {
          "default": "",
          "description": "Analyzed Bitcoin address.",
          "title": "Address",
          "type": "string"
        },
        "include_ai_inferred_labels": {
          "default": false,
          "title": "Include Ai Inferred Labels",
          "type": "boolean"
        },
        "ai_confidence_threshold": {
          "anyOf": [
            {
              "$ref": "#/$defs/AIConfidence"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "source": {
          "additionalProperties": {
            "$ref": "#/$defs/FundAllocation"
          },
          "description": "Source-of-funds breakdown by category.",
          "title": "Source",
          "type": "object"
        },
        "ai_inferred_source": {
          "additionalProperties": {
            "$ref": "#/$defs/FundAllocation"
          },
          "title": "Ai Inferred Source",
          "type": "object"
        },
        "destination": {
          "additionalProperties": {
            "$ref": "#/$defs/FundAllocation"
          },
          "description": "Destination-of-funds breakdown by category.",
          "title": "Destination",
          "type": "object"
        },
        "ai_inferred_destination": {
          "additionalProperties": {
            "$ref": "#/$defs/FundAllocation"
          },
          "title": "Ai Inferred Destination",
          "type": "object"
        },
        "counterparty": {
          "anyOf": [
            {
              "$ref": "#/$defs/Counterparty"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Identified counterparty, if any."
        },
        "ai_inferred_counterparty": {
          "anyOf": [
            {
              "$ref": "#/$defs/Counterparty"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "risk_profile": {
          "additionalProperties": {
            "$ref": "#/$defs/RiskInfluence"
          },
          "description": "Active risk profile, by category.",
          "title": "Risk Profile",
          "type": "object"
        },
        "risky_volume": {
          "anyOf": [
            {
              "$ref": "#/$defs/RiskVolume"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "address_volume": {
          "anyOf": [
            {
              "$ref": "#/$defs/RiskVolume"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "address_balance": {
          "anyOf": [
            {
              "$ref": "#/$defs/AddressBalance"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "run_at_block_height": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Run At Block Height"
        },
        "has_blacklist_flag": {
          "default": false,
          "title": "Has Blacklist Flag",
          "type": "boolean"
        },
        "api_version": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Api Version"
        }
      },
      "title": "AddressRiskResult",
      "type": "object"
    },
    "Counterparty": {
      "description": "An entity on the other side of an address's fund flows.\n\nLabeled entities carry `name`/`category`; AI-inferred counterparties also\ncarry `probability`/`confidence`.",
      "properties": {
        "address": {
          "default": "",
          "description": "Bitcoin address of the counterparty.",
          "title": "Address",
          "type": "string"
        },
        "source": {
          "anyOf": [
            {
              "additionalProperties": {
                "$ref": "#/$defs/FundAllocation"
              },
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Where this counterparty received funds from, by category.",
          "title": "Source"
        },
        "destination": {
          "anyOf": [
            {
              "additionalProperties": {
                "$ref": "#/$defs/FundAllocation"
              },
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Where this counterparty sent funds to, by category.",
          "title": "Destination"
        },
        "received_amount_usd": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Total USD received externally by the cluster/address.",
          "title": "Received Amount Usd"
        },
        "sent_amount_usd": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Total USD sent externally by the cluster/address.",
          "title": "Sent Amount Usd"
        },
        "name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Identified entity name, if labeled.",
          "title": "Name"
        },
        "category": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Entity category, if labeled.",
          "title": "Category"
        },
        "probability": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "ML probability (0-1), AI-inferred counterparties only.",
          "title": "Probability"
        },
        "confidence": {
          "anyOf": [
            {
              "$ref": "#/$defs/AIConfidence"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Confidence level, AI-inferred counterparties only."
        }
      },
      "title": "Counterparty",
      "type": "object"
    },
    "FundAllocation": {
      "description": "A fund-flow allocation for one entity category.\n\n`percentage` is always present. The amount/distance fields are present for\ndetailed allocations and omitted for percentage-only ones.",
      "properties": {
        "percentage": {
          "default": 0.0,
          "description": "Share of the flow (0-1).",
          "title": "Percentage",
          "type": "number"
        },
        "min_distance": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Fewest hops between the address and this category.",
          "title": "Min Distance"
        },
        "amount_usd": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Allocation amount in USD.",
          "title": "Amount Usd"
        },
        "amount_sats": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Allocation amount in satoshis.",
          "title": "Amount Sats"
        }
      },
      "title": "FundAllocation",
      "type": "object"
    },
    "RiskInfluence": {
      "description": "How one risk category contributes to the overall score.",
      "properties": {
        "risk_score": {
          "default": 0.0,
          "description": "Category risk score.",
          "title": "Risk Score",
          "type": "number"
        },
        "receiving_influence": {
          "default": "",
          "description": "Influence of receiving funds from this category.",
          "title": "Receiving Influence",
          "type": "string"
        },
        "sender_influence": {
          "default": "",
          "description": "Influence of sending funds to this category.",
          "title": "Sender Influence",
          "type": "string"
        }
      },
      "title": "RiskInfluence",
      "type": "object"
    },
    "RiskJobState": {
      "description": "Lifecycle state of an analysis job.",
      "enum": [
        "INIT",
        "STARTED",
        "RETRYING",
        "COMPLETED",
        "FAILED"
      ],
      "title": "RiskJobState",
      "type": "string"
    },
    "RiskVolume": {
      "description": "Source/destination volume totals in satoshis and USD.",
      "properties": {
        "source_sats": {
          "default": 0.0,
          "description": "Received (source) volume in sats.",
          "title": "Source Sats",
          "type": "number"
        },
        "destination_sats": {
          "default": 0.0,
          "description": "Sent (destination) volume in sats.",
          "title": "Destination Sats",
          "type": "number"
        },
        "source_usd": {
          "default": 0.0,
          "description": "Received (source) volume in USD.",
          "title": "Source Usd",
          "type": "number"
        },
        "destination_usd": {
          "default": 0.0,
          "description": "Sent (destination) volume in USD.",
          "title": "Destination Usd",
          "type": "number"
        }
      },
      "title": "RiskVolume",
      "type": "object"
    }
  },
  "description": "An address-analysis job. `result` is set once `state` is COMPLETED.",
  "properties": {
    "job_id": {
      "default": "",
      "title": "Job Id",
      "type": "string"
    },
    "state": {
      "$ref": "#/$defs/RiskJobState",
      "default": "INIT"
    },
    "next_update_time": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "UNIX timestamp suggesting when to poll next; null when terminal.",
      "title": "Next Update Time"
    },
    "created_at": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Created At"
    },
    "started_at": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Started At"
    },
    "finished_at": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Finished At"
    },
    "error_message": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Failure detail, set when state is FAILED.",
      "title": "Error Message"
    },
    "result": {
      "anyOf": [
        {
          "$ref": "#/$defs/AddressRiskResult"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    }
  },
  "title": "AddressRiskJob",
  "type": "object"
}

score_tx_address

Risk-score a Bitcoin address in the context of one transaction. Args: tx: Transaction id the address takes part in. address: Bitcoin address to analyze within `tx`. address_side: "withdrawal" if the address is sending funds (analyze the transaction's destinations) or "deposit" if it is receiving funds (analyze the transaction's sources). ai_confidence_threshold: Enable AI-inferred labels at this minimum confidence ("low", "medium", "high"). Omit to disable AI analysis. Returns: A terminal risk job; see `score_address` for the lifecycle. When "COMPLETED" the `result` holds the transaction-specific risk result (`risk_score`, fund tracing, and counterparties). If the job is still pending after SCOREMYCRYPTO_MAX_WAIT, the tool times out and the reserved credit is refunded.

argumenttyperequireddescription
txstringyes
addressstringyes
address_sidestringyes
ai_confidence_thresholdstring | nullno

Returns: TransactionRiskJob

output schema
{
  "$defs": {
    "AIConfidence": {
      "description": "Categorical confidence level of an AI/ML prediction.",
      "enum": [
        "LOW",
        "MED",
        "HIGH"
      ],
      "title": "AIConfidence",
      "type": "string"
    },
    "AddressTxSide": {
      "description": "Which side of a transaction the analyzed address is on.",
      "enum": [
        "deposit",
        "withdrawal"
      ],
      "title": "AddressTxSide",
      "type": "string"
    },
    "Counterparty": {
      "description": "An entity on the other side of an address's fund flows.\n\nLabeled entities carry `name`/`category`; AI-inferred counterparties also\ncarry `probability`/`confidence`.",
      "properties": {
        "address": {
          "default": "",
          "description": "Bitcoin address of the counterparty.",
          "title": "Address",
          "type": "string"
        },
        "source": {
          "anyOf": [
            {
              "additionalProperties": {
                "$ref": "#/$defs/FundAllocation"
              },
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Where this counterparty received funds from, by category.",
          "title": "Source"
        },
        "destination": {
          "anyOf": [
            {
              "additionalProperties": {
                "$ref": "#/$defs/FundAllocation"
              },
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Where this counterparty sent funds to, by category.",
          "title": "Destination"
        },
        "received_amount_usd": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Total USD received externally by the cluster/address.",
          "title": "Received Amount Usd"
        },
        "sent_amount_usd": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Total USD sent externally by the cluster/address.",
          "title": "Sent Amount Usd"
        },
        "name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Identified entity name, if labeled.",
          "title": "Name"
        },
        "category": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Entity category, if labeled.",
          "title": "Category"
        },
        "probability": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "ML probability (0-1), AI-inferred counterparties only.",
          "title": "Probability"
        },
        "confidence": {
          "anyOf": [
            {
              "$ref": "#/$defs/AIConfidence"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Confidence level, AI-inferred counterparties only."
        }
      },
      "title": "Counterparty",
      "type": "object"
    },
    "FundAllocation": {
      "description": "A fund-flow allocation for one entity category.\n\n`percentage` is always present. The amount/distance fields are present for\ndetailed allocations and omitted for percentage-only ones.",
      "properties": {
        "percentage": {
          "default": 0.0,
          "description": "Share of the flow (0-1).",
          "title": "Percentage",
          "type": "number"
        },
        "min_distance": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Fewest hops between the address and this category.",
          "title": "Min Distance"
        },
        "amount_usd": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Allocation amount in USD.",
          "title": "Amount Usd"
        },
        "amount_sats": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Allocation amount in satoshis.",
          "title": "Amount Sats"
        }
      },
      "title": "FundAllocation",
      "type": "object"
    },
    "RiskInfluence": {
      "description": "How one risk category contributes to the overall score.",
      "properties": {
        "risk_score": {
          "default": 0.0,
          "description": "Category risk score.",
          "title": "Risk Score",
          "type": "number"
        },
        "receiving_influence": {
          "default": "",
          "description": "Influence of receiving funds from this category.",
          "title": "Receiving Influence",
          "type": "string"
        },
        "sender_influence": {
          "default": "",
          "description": "Influence of sending funds to this category.",
          "title": "Sender Influence",
          "type": "string"
        }
      },
      "title": "RiskInfluence",
      "type": "object"
    },
    "RiskJobState": {
      "description": "Lifecycle state of an analysis job.",
      "enum": [
        "INIT",
        "STARTED",
        "RETRYING",
        "COMPLETED",
        "FAILED"
      ],
      "title": "RiskJobState",
      "type": "string"
    },
    "TransactionRiskResult": {
      "description": "Risk assessment of an address within the context of one transaction.",
      "properties": {
        "tx": {
          "default": "",
          "description": "Transaction id.",
          "title": "Tx",
          "type": "string"
        },
        "address": {
          "default": "",
          "description": "Analyzed Bitcoin address.",
          "title": "Address",
          "type": "string"
        },
        "side": {
          "anyOf": [
            {
              "$ref": "#/$defs/AddressTxSide"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "amount": {
          "default": 0,
          "description": "Amount attributed to the address, in sats.",
          "title": "Amount",
          "type": "integer"
        },
        "amount_usd": {
          "default": 0.0,
          "description": "Attributed amount in USD.",
          "title": "Amount Usd",
          "type": "number"
        },
        "risk_score": {
          "default": 0.0,
          "description": "Transaction-specific risk score.",
          "title": "Risk Score",
          "type": "number"
        },
        "funds": {
          "additionalProperties": {
            "$ref": "#/$defs/FundAllocation"
          },
          "description": "Traced funds by entity category.",
          "title": "Funds",
          "type": "object"
        },
        "include_ai_inferred_labels": {
          "default": false,
          "title": "Include Ai Inferred Labels",
          "type": "boolean"
        },
        "ai_confidence_threshold": {
          "anyOf": [
            {
              "$ref": "#/$defs/AIConfidence"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "counterparty": {
          "description": "Counterparties on the other side of the tx.",
          "items": {
            "$ref": "#/$defs/Counterparty"
          },
          "title": "Counterparty",
          "type": "array"
        },
        "ai_inferred_counterparty": {
          "items": {
            "$ref": "#/$defs/Counterparty"
          },
          "title": "Ai Inferred Counterparty",
          "type": "array"
        },
        "risk_profile": {
          "additionalProperties": {
            "$ref": "#/$defs/RiskInfluence"
          },
          "title": "Risk Profile",
          "type": "object"
        },
        "risky_volume_sats": {
          "default": 0.0,
          "title": "Risky Volume Sats",
          "type": "number"
        },
        "risky_volume_usd": {
          "default": 0.0,
          "title": "Risky Volume Usd",
          "type": "number"
        },
        "run_at_block_height": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Run At Block Height"
        },
        "has_blacklist_flag": {
          "default": false,
          "title": "Has Blacklist Flag",
          "type": "boolean"
        },
        "api_version": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Api Version"
        }
      },
      "title": "TransactionRiskResult",
      "type": "object"
    }
  },
  "description": "A transaction-analysis job. `result` is set once `state` is COMPLETED.",
  "properties": {
    "job_id": {
      "default": "",
      "title": "Job Id",
      "type": "string"
    },
    "state": {
      "$ref": "#/$defs/RiskJobState",
      "default": "INIT"
    },
    "next_update_time": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "UNIX timestamp suggesting when to poll next; null when terminal.",
      "title": "Next Update Time"
    },
    "created_at": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Created At"
    },
    "started_at": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Started At"
    },
    "finished_at": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Finished At"
    },
    "error_message": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Failure detail, set when state is FAILED.",
      "title": "Error Message"
    },
    "result": {
      "anyOf": [
        {
          "$ref": "#/$defs/TransactionRiskResult"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    }
  },
  "title": "TransactionRiskJob",
  "type": "object"
}

Payments & credits (3)

buy_credits

Create a PaidlyInteractive checkout invoice for this bearer token. Each credit currently costs PRICE_SATS_PER_CREDIT, defaulting to 99 sats. The returned bolt11_invoice should be paid by the user. Credits are applied when the invoice settles via webhook; use check_payment to poll.

argumenttyperequireddescription
credit_countintegerno

Returns: buy_creditsDictOutput

output schema
{
  "additionalProperties": true,
  "title": "buy_creditsDictOutput",
  "type": "object"
}

check_payment

Poll PaidlyInteractive for one of this token's invoices.

argumenttyperequireddescription
invoice_idstringyes

Returns: check_paymentDictOutput

output schema
{
  "additionalProperties": true,
  "title": "check_paymentDictOutput",
  "type": "object"
}

get_balance

Return the current credit balance for the authenticated bearer token.

No arguments.

Returns: get_balanceDictOutput

output schema
{
  "additionalProperties": true,
  "title": "get_balanceDictOutput",
  "type": "object"
}