diff --git a/blockapi/test/v2/api/test_blockonomics.py b/blockapi/test/v2/api/test_blockonomics.py new file mode 100644 index 0000000..c91f13b --- /dev/null +++ b/blockapi/test/v2/api/test_blockonomics.py @@ -0,0 +1,106 @@ +from decimal import Decimal + +import pytest +from requests.exceptions import ConnectionError, ReadTimeout + +from blockapi.v2.api import BlockonomicsApi +from blockapi.v2.base import ApiException +from blockapi.v2.models import FetchResult + +# Deliberately synthetic identifiers: these tests never access a live wallet. +KEY = 'synthetic-api-key' +URL = 'https://www.blockonomics.co/api/balance' + + +def row(address='synthetic-derived-address', confirmed=123456789, unconfirmed=0): + return dict(addr=address, confirmed=confirmed, unconfirmed=unconfirmed) + + +@pytest.mark.parametrize( + 'address', ['synthetic-address', 'xpubSynthetic', 'ypubSynthetic', 'zpubSynthetic'] +) +def test_fetch_and_aggregate(requests_mock, address): + payload = { + 'response': [ + row(confirmed=123456789, unconfirmed=999), + row('synthetic-change-address', 1, -10), + ] + } + requests_mock.get(URL, json=payload) + balances = BlockonomicsApi(api_key=KEY).get_balance(address) + assert len(balances) == 1 + assert balances[0].balance == Decimal('1.23456790') + assert balances[0].raw == payload + request = requests_mock.last_request + assert request.headers['Authorization'] == 'Bearer ' + KEY + assert request.qs == {'addr': [address.lower()]} + assert KEY not in request.url + assert request.timeout == (5, 30) + + +def test_zero_excludes_unconfirmed(requests_mock): + requests_mock.get(URL, json={'response': [row(confirmed=0, unconfirmed=100)]}) + assert BlockonomicsApi(api_key=KEY).get_balance('synthetic-address') == [] + + +def test_missing_key_does_not_request(requests_mock): + with pytest.raises(ApiException, match='API key'): + BlockonomicsApi().get_balance('synthetic-address') + assert requests_mock.call_count == 0 + + +@pytest.mark.parametrize('address', ['', 'first second', 'first\nsecond']) +def test_reject_batch_input(requests_mock, address): + with pytest.raises(ApiException, match='Expected one'): + BlockonomicsApi(api_key=KEY).get_balance(address) + assert requests_mock.call_count == 0 + + +@pytest.mark.parametrize('status', [401, 403, 429, 500, 502]) +def test_http_error_not_zero(requests_mock, status): + requests_mock.get(URL, status_code=status, json={'message': 'unavailable'}) + with pytest.raises(ApiException): + BlockonomicsApi(api_key=KEY).get_balance('synthetic-address') + + +@pytest.mark.parametrize( + 'error', [ConnectionError('disconnected'), ReadTimeout('timeout')] +) +def test_transport_error_not_zero(requests_mock, error): + requests_mock.get(URL, exc=error) + with pytest.raises(ApiException): + BlockonomicsApi(api_key=KEY).get_balance('synthetic-address') + + +def test_invalid_json(requests_mock): + requests_mock.get(URL, text='error') + with pytest.raises(ApiException, match='Invalid JSON'): + BlockonomicsApi(api_key=KEY).get_balance('synthetic-address') + + +@pytest.mark.parametrize( + 'data', + [ + None, + {}, + [], + {'response': []}, + {'response': {}}, + {'response': [None]}, + {'response': [{}]}, + {'response': [row(confirmed=True)]}, + {'response': [row(confirmed=-1)]}, + {'response': [row(confirmed='1')]}, + {'response': [row(confirmed=1.5)]}, + {'response': [row(address=None)]}, + {'response': [row(), row()]}, + ], +) +def test_invalid_response_not_zero(data): + with pytest.raises(ApiException): + BlockonomicsApi().parse_balances(FetchResult(data=data)) + + +def test_direct_parse_preserves_error(): + with pytest.raises(ApiException, match='unavailable'): + BlockonomicsApi().parse_balances(FetchResult(errors=['unavailable'])) diff --git a/blockapi/v2/api/__init__.py b/blockapi/v2/api/__init__.py index 2864c1b..6970f3a 100644 --- a/blockapi/v2/api/__init__.py +++ b/blockapi/v2/api/__init__.py @@ -7,6 +7,7 @@ BlockchairDogecoinApi, BlockchairLitecoinApi, ) +from blockapi.v2.api.blockonomics import BlockonomicsApi from blockapi.v2.api.chainso import ChainSoLitecoinApi from blockapi.v2.api.debank import DebankApi, DebankApp, DebankPrediction from blockapi.v2.api.ethplorer import EthplorerApi diff --git a/blockapi/v2/api/blockonomics.py b/blockapi/v2/api/blockonomics.py new file mode 100644 index 0000000..e15f3b6 --- /dev/null +++ b/blockapi/v2/api/blockonomics.py @@ -0,0 +1,89 @@ +from blockapi.v2.base import ApiException, BalanceMixin, BlockchainApi +from blockapi.v2.coins import COIN_BTC +from blockapi.v2.models import ( + ApiOptions, + AssetType, + BalanceItem, + Blockchain, + FetchResult, + ParseResult, +) + + +class BlockonomicsApi(BlockchainApi, BalanceMixin): + """BTC balances for addresses and xpub/ypub/zpub extended public keys. + + Requires a Blockonomics API key. Only provider-confirmed balances are + included: Blockonomics classifies fewer than two confirmations as + unconfirmed. Extended-key discovery follows the provider's gap policy. + Docs: https://developers.blockonomics.co/docs/search/getbalance + """ + + coin = COIN_BTC + api_options = ApiOptions( + blockchain=Blockchain.BITCOIN, + base_url='https://www.blockonomics.co/api/', + rate_limit=1, + ) + supported_requests = {'get_balance': 'balance'} + request_timeout = (5, 30) + + def _get_response(self, request_method, headers, params, req_args): + return self._session.get( + self._build_request_url(request_method, **req_args), + headers=headers, + params=params, + timeout=self.request_timeout, + ) + + def fetch_balances(self, address: str) -> FetchResult: + if not self.api_key: + return FetchResult(errors=['Blockonomics API key is required']) + # One wallet per request; whitespace is the provider's batch separator. + if not address or any(char.isspace() for char in address): + return FetchResult(errors=['Expected one Bitcoin address or extended key']) + try: + return self.get_data( + 'get_balance', + headers={'Authorization': f'Bearer {self.api_key}'}, + params={'addr': address}, + ) + except ValueError: + return FetchResult(errors=['Invalid JSON in Blockonomics response']) + + def parse_balances(self, fetch_result: FetchResult) -> ParseResult: + if fetch_result.errors: + raise ApiException(fetch_result.errors[0]) + data = fetch_result.data + rows = data.get('response') if isinstance(data, dict) else None + if not isinstance(rows, list) or not rows: + raise ApiException('Invalid Blockonomics response: missing balance rows') + addresses = set() + balance_raw = 0 + for row in rows: + if not isinstance(row, dict): + raise ApiException('Invalid Blockonomics balance row') + address = row.get('addr') + confirmed = row.get('confirmed') + if ( + not isinstance(address, str) + or not address + or address in addresses + or type(confirmed) is not int + or confirmed < 0 + ): + raise ApiException('Invalid Blockonomics balance row') + addresses.add(address) + balance_raw += confirmed + if not balance_raw: + return ParseResult() + return ParseResult( + data=[ + BalanceItem.from_api( + balance_raw=balance_raw, + coin=self.coin, + asset_type=AssetType.AVAILABLE, + raw=data, + ) + ] + )