{"id":26436164,"url":"https://github.com/santiment/sanpy","last_synced_at":"2025-05-16T06:06:27.835Z","repository":{"id":32709145,"uuid":"139407496","full_name":"santiment/sanpy","owner":"santiment","description":"Santiment API Python Client","archived":false,"fork":false,"pushed_at":"2025-04-16T13:21:23.000Z","size":1143,"stargazers_count":102,"open_issues_count":6,"forks_count":29,"subscribers_count":15,"default_branch":"master","last_synced_at":"2025-04-16T19:49:59.841Z","etag":null,"topics":["blockchain","data-science","machine-learning","numpy","pandas","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/santiment.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-07-02T07:33:48.000Z","updated_at":"2025-04-16T13:19:10.000Z","dependencies_parsed_at":"2024-06-19T05:17:27.884Z","dependency_job_id":"18e1de9f-f6aa-4f52-9173-8f1a8f0d54ac","html_url":"https://github.com/santiment/sanpy","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/santiment%2Fsanpy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/santiment%2Fsanpy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/santiment%2Fsanpy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/santiment%2Fsanpy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/santiment","download_url":"https://codeload.github.com/santiment/sanpy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254478190,"owners_count":22077676,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blockchain","data-science","machine-learning","numpy","pandas","python"],"created_at":"2025-03-18T08:15:11.286Z","updated_at":"2025-05-16T06:06:22.811Z","avatar_url":"https://github.com/santiment.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# sanpy\n---\n[![PyPI version](https://badge.fury.io/py/sanpy.svg)](https://badge.fury.io/py/sanpy)\n\nPython client for cryptocurrency data from [Santiment API](https://api.santiment.net/).\nThis library provides utilities for accessing the GraphQL Santiment API endpoint\nand convert the result to pandas dataframe.\n\nMore documentation regarding the API and definitions of metrics can be found on [Santiment Academy]()\n\n# Table of contents\n\n- [sanpy](#sanpy)\n- [Table of contents](#table-of-contents)\n  - [Installation](#installation)\n  - [Upgrade to latest version](#upgrade-to-latest-version)\n  - [Install extra packages](#install-extra-packages)\n  - [Restricted metrics](#restricted-metrics)\n  - [Configuration](#configuration)\n    - [Read the API key from the environment](#read-the-api-key-from-the-environment)\n    - [Manually configure an API key](#manually-configure-an-api-key)\n    - [How to obtain an API key](#how-to-obtain-an-api-key)\n  - [Getting the data](#getting-the-data)\n    - [Using the provided functions](#using-the-provided-functions)\n    - [Execute an arbitrary GraphQL request](#execute-an-arbitrary-graphql-request)\n  - [Execute SQL queries and get the result](#execute-sql-queries-and-get-the-result)\n  - [Available metrics](#available-metrics)\n  - [Available Metrics for Slug](#available-metrics-for-slug)\n  - [Fetch timeseries metric](#fetch-timeseries-metric)\n  - [Fetching metadata for a metric](#fetching-metadata-for-a-metric)\n  - [Batching multiple queries](#batching-multiple-queries)\n  - [Rate Limit Tools](#rate-limit-tools)\n  - [Metric Complexity](#metric-complexity)\n  - [Include Incomplete Data Flag](#include-incomplete-data-flag)\n  - [Metric/Asset pair available cince](#metricasset-pair-available-cince)\n  - [Transform the result](#transform-the-result)\n  - [Available projects](#available-projects)\n  - [Non-standard metrics](#non-standard-metrics)\n    - [Other Price metrics](#other-price-metrics)\n      - [Marketcap, Price USD, Price BTC and Trading Volume](#marketcap-price-usd-price-btc-and-trading-volume)\n      - [Open, High, Close, Low Prices, Volume, Marketcap](#open-high-close-low-prices-volume-marketcap)\n    - [Historical Balance](#historical-balance)\n    - [Ethereum Top Transactions](#ethereum-top-transactions)\n    - [Ethereum Spent Over Time](#ethereum-spent-over-time)\n    - [Token Top Transactions](#token-top-transactions)\n    - [Top Transfers](#top-transfers)\n    - [Emerging Trends](#emerging-trends)\n  - [Extras](#extras)\n  - [Development](#development)\n  - [Running tests](#running-tests)\n  - [Running integration tests](#running-integration-tests)\n\n## Installation\n\nTo install the latest [sanpy from PyPI](https://pypi.org/project/sanpy/):\n```bash\npip install sanpy\n```\n\n## Upgrade to latest version\n\n```bash\npip install --upgrade sanpy\n```\n\n## Install extra packages\n\nThere are few scripts under [extras](/san/extras) directory related to backtesting and event studies. To install their dependencies use:\n\n```bash\npip install sanpy[extras]\n```\n\n## Restricted metrics\n\nIn order to access real-time data or historical data for some of the metrics,\nyou'll need to set the [API key](#configuration), generated from an account with\na paid API plan.\n\n## Configuration\n\nYou can provide an API key which gives access to the restricted metrics in two different ways:\n\n### Read the API key from the environment\n\nDuring loading of the `san` module, if the `SANPY_APIKEY` exists, its content\nis read and set as the API key.\n\n```shell\nexport SANPY_APIKEY=\"my_apikey\"\n```\n```python\nimport san\n\u003e\u003e\u003e san.ApiConfig.api_key\n'my_apikey'\n```\n\n### Manually configure an API key\n\n```python\nimport san\nsan.ApiConfig.api_key = \"my_apikey\"\n```\n\n### How to obtain an API key\n\nTo obtain an API key you should [log in to sanbase](https://app.santiment.net/login)\nand go to the `Account` page - [https://app.santiment.net/account](https://app.santiment.net/account).\nThere is an `API Keys` section and a `Generate new api key` button.\n\n## Getting the data\n\n### Using the provided functions\n\nThe library provides the `get` and `get_many` functions that are used to fetch data.\n`get` is used to fetch timeseries data for a single metric/asset pair.\n`get_many` is used to fetch timeseries data for a single metric, but many assets. This is counted as 1 API call.\n\nThe first argument to the functions is the metric name.\n\nThe rest of the parameters are::\n\n- `slug` - (for `get`) The project identificator, as seen in [the Available projects section](#available-projects)\n- `slugs` - (for `get_many`) A list of projects' identificators, as seen in [the Available projects section](#available-projects)\n- `selector` - Allow for more flexible selection of the target. Some metrics are\n  computed on blockchain addresses, for others you can provide a list of slugs,\n  labels, amount of top holders. etc.\n- `from_date` - A date or datetime in ISO8601 format specifying the start of the queried period. Defaults to `datetime.utcnow() - 365 days` \n- `to_date` - A date or datetime in ISO86091 format specifying the end of the queried period. Defaults to `datetime.utcnow()`\n- `interval` - The interval between the data points in the timeseries. Defaults to `'1d'`\n  It is represented in two different ways:\n  - a fixed range:  an integer followed by one of: `s`, `m`, `h`, `d` or `w`\n  - a function, providing some semantic or a dynamic range: `toStartOfMonth`, `toStartOfDay`, `toStartOfWeek`, `toMonday`..\n\nThe returned result for time-series data is transformed into `pandas DataFrame` and is indexed by `datetime`.\nFor `get`, the value column is named `value`.\nFor `get_many`, there is one column per asset queried. The asset slugs are used for the column names.\n\nFor backwards compatibility, fetching the metric by providing `\"metric/slug\"` as\nthe first instead of using a separate `'slug'`/`'selector'` continues to work,\nbut it is not the recommended approach.\n\nFor non-metric related data like getting the list of available assets, the data\nis fetched by providing a string in the format `query/argument` and additional\nparameters.\n\nThe examples below contain some of the described scenarios.\n\nFetch metric by providing `metric` as first argument and `slug` as named parameter:\n\n```python\nimport san\nsan.get(\n  \"price_usd\",\n  slug=\"bitcoin\",\n  from_date=\"2022-01-01\",\n  to_date=\"2022-01-05\",\n  interval=\"1d\"\n)\n```\n```\ndatetime                   value\n2022-01-01 00:00:00+00:00  47686.811509\n2022-01-02 00:00:00+00:00  47345.220564\n2022-01-03 00:00:00+00:00  46458.116959\n2022-01-04 00:00:00+00:00  45928.661063\n2022-01-05 00:00:00+00:00  43569.003348\n```\n\nFetch prices for multiple assets:\n```python\nimport san\nsan.get_many(\n  \"price_usd\",\n  slugs=[\"bitcoin\", \"ethereum\", \"tether\"],\n  from_date=\"2022-01-01\",\n  to_date=\"2022-01-05\",\n  interval=\"1d\"\n)\n```\n```\ndatetime                   bitcoin       ethereum     tether                                            \n2022-01-01 00:00:00+00:00  47686.811509  3769.696916  1.000500\n2022-01-02 00:00:00+00:00  47345.220564  3829.565045  1.000460\n2022-01-03 00:00:00+00:00  46458.116959  3761.380274  1.000165\n2022-01-04 00:00:00+00:00  45928.661063  3795.890130  1.000208\n2022-01-05 00:00:00+00:00  43569.003348  3550.386882  1.000122\n```\n\nFetch development activity of a specific Github organization:\n```python\nimport san\nsan.get(\n  \"dev_activity\",\n  selector={\"organization\": \"google\"},\n  from_date=\"2022-01-01\",\n  to_date=\"2022-01-05\",\n  interval=\"1d\"\n)\n```\n```\ndatetime                    value     \n2022-01-01 00:00:00+00:00   176.0\n2022-01-02 00:00:00+00:00   129.0\n2022-01-03 00:00:00+00:00   562.0\n2022-01-04 00:00:00+00:00  1381.0\n2022-01-05 00:00:00+00:00  1334.0\n```\n\nFetch a metric for a contract address, not a slug:\n```python\nimport san\nsan.get(\n  \"contract_transactions_count\",\n  selector={\"contractAddress\": \"0x00000000219ab540356cBB839Cbe05303d7705Fa\"},\n  from_date=\"2022-01-01\",\n  to_date=\"2022-01-05\",\n  interval=\"1d\"\n)\n```\n```\ndatetime                   value     \n2022-01-01 00:00:00+00:00   90.0\n2022-01-02 00:00:00+00:00  339.0\n2022-01-03 00:00:00+00:00  486.0\n2022-01-04 00:00:00+00:00  314.0\n2022-01-05 00:00:00+00:00  328.0\n```\n\nFetch top holders metric and specify the number of top holders to be counted:\n```python\nimport san\nsan.get(\n  \"amount_in_top_holders\",\n  selector={\"slug\": \"santiment\", \"holdersCount\": 10},\n  from_date=\"2022-01-01\",\n  to_date=\"2022-01-05\",\n  interval=\"1d\"\n)\n```\n```\ndatetime                   value\n2022-01-01 00:00:00+00:00  7.391186e+07\n2022-01-02 00:00:00+00:00  7.391438e+07\n2022-01-03 00:00:00+00:00  7.391984e+07\n2022-01-04 00:00:00+00:00  7.391984e+07\n2022-01-05 00:00:00+00:00  7.391984e+07\n```\n\nFetch trade volume of a given DEX for a given slug\n```python\nimport san\n# This requires Santiment API PRO apikey configured\nsan.get(\n  \"total_trade_volume_by_dex\",\n  selector={\"slug\": \"ethereum\", \"label\": \"decentralized_exchange\", \"owner\": \"UniswapV2\"},\n  from_date=\"2022-01-01\",\n  to_date=\"2022-01-05\",\n  interval=\"1d\"\n)\n```\n```\ndatetime                    value\n2022-01-01 00:00:00+00:00   96882.176846\n2022-01-02 00:00:00+00:00   85184.970249\n2022-01-03 00:00:00+00:00  107489.846163\n2022-01-04 00:00:00+00:00  105204.677503\n2022-01-05 00:00:00+00:00  174178.848916\n```\nFetch metric by providing `metric/slug` as first argument and no `slug` as named parameter:\n```python\nimport san\n\nsan.get(\n    \"daily_active_addresses/bitcoin\",\n    from_date=\"2018-06-01\",\n    to_date=\"2018-06-05\",\n    interval=\"1d\"\n)\n```\n```\ndatetime                   value      \n2018-06-01 00:00:00+00:00  692508.0\n2018-06-02 00:00:00+00:00  521887.0\n2018-06-03 00:00:00+00:00  531464.0\n2018-06-04 00:00:00+00:00  702902.0\n2018-06-05 00:00:00+00:00  655695.0\n```\n\nFetch non-timeseries data:\n```python\nimport san\nsan.get(\"projects/all\")\n```\n```\n                name             slug ticker   totalSupply\n0             0chain           0chain    ZCN     400000000\n1                 0x               0x    ZRX    1000000000\n2          0xBitcoin            0xbtc  0xBTC      20999984\n...\n```\n\n### Execute an arbitrary GraphQL request\n\nSome of the available queries in the [Santiment API](https://api.santiment.net) do not have a \ndedicated sanpy function. Alternatively, if the returned format needs to be parsed differently, this approach\ncan be used, too. They can be fetched by providing the raw GraphQL query.\n\nFetching data for many slugs at the same time. Note that this is also available as `san.get_many`\n```python\nimport san\nimport pandas as pd\n\nresult = san.graphql.execute_gql(\"\"\"\n{\n  getMetric(metric: \"price_usd\") {\n    timeseriesDataPerSlug(\n      selector: {slugs: [\"ethereum\", \"bitcoin\"]}\n      from: \"2022-05-05T00:00:00Z\"\n      to: \"2022-05-08T00:00:00Z\"\n      interval: \"1d\") {\n        datetime\n        data{\n          value\n          slug\n        }\n    }\n  }\n}\n\"\"\")\n\ndata = result['getMetric']['timeseriesDataPerSlug']\nrows = []\nfor datetime_point in data:\n    row = {'datetime': datetime_point['datetime']}\n    for slug_data in datetime_point['data']:\n        row[slug_data['slug']] = slug_data['value']\n    rows.append(row)\n\ndf = pd.DataFrame(rows)\ndf.set_index('datetime', inplace=True)\n```\n```\ndatetime              bitcoin       ethereum                \n2022-05-05T00:00:00Z  36575.142133  2749.213042\n2022-05-06T00:00:00Z  36040.922350  2694.979684\n2022-05-07T00:00:00Z  35501.954144  2636.092958\n```\n\nFetching a specific set of fields for a project:\n```python\nimport san\nimport pandas as pd\n\nresult = san.graphql.execute_gql(\"\"\"{\n  projectBySlug(slug: \"santiment\") {\n    slug\n    name\n    ticker\n    infrastructure\n    mainContractAddress\n    twitterLink\n  }\n}\"\"\")\n\npd.DataFrame(result[\"projectBySlug\"], index=[0])\n```\n\n```\n  infrastructure                         mainContractAddress       name       slug ticker                        twitterLink\n0            ETH  0x7c5a0ce9267ed19b22f8cae653f198e3e8daf098  Santiment  santiment    SAN  https://twitter.com/santimentfeed\n```\n\n## Execute SQL queries and get the result\n\nOne of the Santiment products is [Santiment Queries](https://academy.santiment.net/santiment-queries/). It allows you to execute SQL queries on a database hosted by Santiment. Explore the documentation in order to get familiar with the available data and how to write SQL queries.\n\nIn order to execute a query you need to provide your API key.\n\nExecuting a query and getting the result as a pandas DataFrame:\n```python\nimport san\nsan.execute_sql(query=\"SELECT * FROM daily_metrics_v2 LIMIT 5\")\n```\n```\n   metric_id  asset_id                    dt  value           computed_at\n0         10      1369  2015-07-17T00:00:00Z    0.0  2020-10-21T08:48:42Z\n1         10      1369  2015-07-18T00:00:00Z    0.0  2020-10-21T08:48:42Z\n2         10      1369  2015-07-19T00:00:00Z    0.0  2020-10-21T08:48:42Z\n3         10      1369  2015-07-20T00:00:00Z    0.0  2020-10-21T08:48:42Z\n4         10      1369  2015-07-21T00:00:00Z    0.0  2020-10-21T08:48:42Z\n```\n\nIn order to change the index to one of the columns, provide the `set_index` parameter:\n```python\nimport san\nsan.execute_sql(query=\"SELECT * FROM daily_metrics_v2 LIMIT 5\", set_index=\"dt\")\n```\n```\ndt                    metric_id  asset_id  value           computed_at\n2015-07-17T00:00:00Z         10      1369    0.0  2020-10-21T08:48:42Z\n2015-07-18T00:00:00Z         10      1369    0.0  2020-10-21T08:48:42Z\n2015-07-19T00:00:00Z         10      1369    0.0  2020-10-21T08:48:42Z\n2015-07-20T00:00:00Z         10      1369    0.0  2020-10-21T08:48:42Z\n2015-07-21T00:00:00Z         10      1369    0.0  2020-10-21T08:48:42Z\n```\n\nThe queries can be parametrized. In the query the parameters are named parameters,\nsurrounded by two curly brackets `{{key}}`. The parameters is a dictionary. The query\ncan be a multiline string:\n\n```python\nsan.execute_sql(query=\"\"\"\n  SELECT\n    get_metric_name(metric_id) AS metric,\n    get_asset_name(asset_id) AS asset,\n    dt,\n    argMax(value, computed_at)\n  FROM daily_metrics_v2\n  WHERE\n    asset_id = get_asset_id({{slug}}) AND\n    metric_id = get_metric_id({{metric}}) AND\n    dt \u003e= now() - INTERVAL {{last_n_days}} DAY\n  GROUP BY dt, metric_id, asset_id\n  ORDER BY dt ASC\n\"\"\",\nparameters={'slug': 'bitcoin', 'metric': 'daily_active_addresses', 'last_n_days': 7},\nset_index=\"dt\")\n```\n```\ndt                                    metric    asset        value                     \n2023-03-22T00:00:00Z  daily_active_addresses  bitcoin     941446.0\n2023-03-23T00:00:00Z  daily_active_addresses  bitcoin     913215.0\n2023-03-24T00:00:00Z  daily_active_addresses  bitcoin     884271.0\n2023-03-25T00:00:00Z  daily_active_addresses  bitcoin     906851.0\n2023-03-26T00:00:00Z  daily_active_addresses  bitcoin     835596.0\n2023-03-27T00:00:00Z  daily_active_addresses  bitcoin    1052637.0\n2023-03-28T00:00:00Z  daily_active_addresses  bitcoin     311566.0\n```\n\n## Available metrics\n\nGetting all of the metrics as a list is done using the following code:\n\n```python\nsan.available_metrics()\n```\n\n## Available Metrics for Slug\n\nGetting all of the metrics for a given slug is achieved with the following code:\n\n```python\nsan.available_metrics_for_slug(\"santiment\")\n```\n## Fetch timeseries metric\n\n```python\nimport san\n\nsan.get(\n    \"daily_active_addresses\",\n    slug=\"santiment\",\n    from_date=\"2018-06-01\",\n    to_date=\"2018-06-05\",\n    interval=\"1d\"\n)\n```\n\nUsing the defaults params (last 1 year of data with 1 day interval):\n\n```python\nsan.get(\"daily_active_addresses\", slug=\"santiment\")\nsan.get(\"price_usd\", slug=\"santiment\")\n```\n\n## Fetching metadata for a metric\n\nFetching the metadata for an on-chain metric.\n\n```python\nsan.metadata(\n    \"nvt\",\n    arr=[\"availableSlugs\", \"defaultAggregation\", \"humanReadableName\", \"isAccessible\", \"isRestricted\", \"restrictedFrom\", \"restrictedTo\"]\n)\n```\n\nExample result:\n\n```python\n{\"availableSlugs\": [\"0chain\", \"0x\", \"0xbtc\", \"0xcert\", \"1sg\", ...],\n\"defaultAggregation\": \"AVG\", \"humanReadableName\": \"NVT (Using Circulation)\", \"isAccessible\": True, \"isRestricted\": True, \"restrictedFrom\": \"2020-03-21T08:44:14Z\", \"restrictedTo\": \"2020-06-17T08:44:14Z\"}\n```\n\n- `availableSlugs` - A list of all slugs available for this metric.\n- `defaultAggregation` - If big interval are queried, all values that fall into\n  this interval will be aggregated with this aggregation.\n- `humanReadableName` - A name of the metric suitable for showing to users.\n- `isAccessible` - `True` if the metric is accessible. If API key is configured, c\n  hecks the API plan subscriptions. `False` if the metric is not accessible. For example\n  `circulation_1d` requires `PRO` plan subscription in order to be accessible at\n  all.\n- `isRestricted` - `True` if time restrictions apply to the metric and your\n  current plan (`Free` if no API key is configured). Check `restrictedFrom` and\n  `restrictedTo`.\n- `restrictedFrom` - The first datetime available of that metric for your current plan.\n- `restrictedTo` - The last datetime available of that metric and your current plan.\n\n## Batching multiple queries\n\nMultiple queries can be executed in a batch to speed up the performance.\n\nThere are two batch classes provided - `Batch` and `AsyncBatch`.\n\n\u003e Note: Batching improves the performance and the developer experience, but every\n\u003e query put inside the batch is still counted as one separate API call.\n\u003e To fetch a metric for multiple assets at a time take a look at `san.get_many`\n  \n- `AsyncBatch` is the recommended batch class. It executes all the queries in\n  separate HTTP requests. The benefit of using `AsyncBatch` over looping and\n  executing every API call is that the queries can be executed concurrently. \n  Putting multiple API calls in separate HTTP calls also allows to fetch more\n  data, otherwise you might run into [Complexity](https://academy.santiment.net/for-developers/#graphql-api-complexity) issues. \n  The concurrency is controlled by the `max_workers` optional parameter to the\n  `execute` function. By default the `max_workers` value is 10.\n  It also supports `get_many` function to fetch data for many assets.\n\n- `Batch` combines all the provided queries in a single GraphQL document and\n  executes them in a single HTTP request. This batching technique should be used\n  when lightweight queries that don't fetch a lot of data are used. The reason is\n  that the [complexity](https://academy.santiment.net/for-developers/#graphql-api-complexity) of each query\n  is accumulated and the batch can be rejected.\n  \nNote: If you have been using `Batch()` and want to switch to the newer `AsyncBatch()` you only need to\nchange the batch initialization. The functions for adding queries and executing the batch, as well as the\nformat of the response, are the same.\n\n```python\nfrom san import Batch\n\nbatch = Batch()\n\nbatch.get(\n    \"daily_active_addresses\",\n    slug=\"santiment\",\n    from_date=\"2018-06-01\",\n    to_date=\"2018-06-05\",\n    interval=\"1d\"\n)\n\nbatch.get(\n    \"transaction_volume\",\n    slug=\"santiment\",\n    from_date=\"2018-06-01\",\n    to_date=\"2018-06-05\",\n    interval=\"1d\"\n)\n\n[daa, trx_volume] = batch.execute()\n```\n\n```python\nfrom san import AsyncBatch\n\nbatch = AsyncBatch()\n\nbatch.get(\n    \"daily_active_addresses\",\n    slug=\"santiment\",\n    from_date=\"2018-06-01\",\n    to_date=\"2018-06-05\",\n    interval=\"1d\"\n)\nbatch.get_many(\n    \"daily_active_addresses\",\n    slugs=[\"bitcoin\", \"ethereum\"],\n    from_date=\"2018-06-01\",\n    to_date=\"2018-06-05\",\n    interval=\"1d\"\n)\n[daa, daa_many] = batch.execute(max_workers=10)\n```\n\n## Rate Limit Tools\n\nThere are two functions, which can help you in handling the rate limits:\n* ``is_rate_limit_exception`` - Returns whether the exception caught is because of rate limitation\n* ``rate_limit_time_left`` - Returns the time left before the rate limit expires\n* ``api_calls_made`` - Returns the API calls for each day in which it was used\n* ``api_calls_remaining`` - Returns the API calls remaining for the month, hour and minute\n\nExample:\n```python\nimport time\nimport san\n\ntry:\n  san.get(\n    \"price_usd\",\n    slug=\"santiment\",\n    from_date=\"utc_now-30d\",\n    to_date=\"utc_now\",\n    interval=\"1d\"\n  )\nexcept Exception as e:\n  if san.is_rate_limit_exception(e):\n    rate_limit_seconds = san.rate_limit_time_left(e)\n    print(f\"Will sleep for {rate_limit_seconds}\")\n    time.sleep(rate_limit_seconds)\n\n...\n\ncalls_by_day = san.api_calls_made()\ncalls_remaining = san.api_calls_remaining()\n```\n\n\n## Metric Complexity\n\nFetch the complexity of a metric. The complexity depends on the from/to/interval\nparameters, as well as the metric and the subscription plan. A request might\nhave a maximum complexity of 50000. If a request has a higher complexity there\nare a few ways to solve the issue:\n\n- Break down the request into multiple requests with smaller from-to ranges.\n- Upgrade to a higher subscription plan.\n\nMore about the complexity can be found on [Santiment Academy]()\n```python\nsan.metric_complexity(\n    metric=\"price_usd\",\n    from_date=\"2020-01-01\",\n    to_date=\"2020-02-20\",\n    interval=\"1d\"\n)\n```\n\n## Include Incomplete Data Flag\n\nDaily metrics have one value per day. For the current day, the latest computed\nvalue will not include a full day of data. For example, computing\n`daily_active_addresses` at 08:00 includes data for one third of the day. To\nreduce confusion, the current day value for metrics that have this behaviour is\nexcluded. To force fetching the current day value, the `includeIncompleteData`\nflag must be used.\n\n```python\nsan.get(\n  \"daily_active_addresses/bitcoin\",\n  from_date=\"utc_now-3d\",\n  to_date=\"utc_now\",\n  interval=\"1d\",\n  include_incomplete_data=True\n)\n```\n\n## Metric/Asset pair available cince\n\nFetch the first datetime for which a metric is available for a given slug.\n\n```python\nsan.available_metric_for_slug_since(metric=\"daily_active_addresses\", slug=\"santiment\")\n```\n\n## Transform the result\n\nExample usage:\n```python\nsan.get(\n  \"price_usd\",\n  slug=\"santiment\",\n  from_date=\"2020-06-01\",\n  to_date=\"2021-06-05\",\n  interval=\"1d\",\n  transform={\"type\": \"moving_average\", \"moving_average_base\": 100},\n  aggregation=\"LAST\"\n)\n```\n\nWhere the parameters, that are not mentioned, are optional:\n\n`transform` - Apply a transformation on the data. The supported transformations are:\n- \"moving_average\" - Replace every value V\u003csub\u003ei\u003c/sub\u003e with the average of the last \"moving_average_base\" values.\n- \"consecutive_differences\" - Replace every value V\u003csub\u003ei\u003c/sub\u003e with the value V\u003csub\u003ei\u003c/sub\u003e - V\u003csub\u003ei-1\u003c/sub\u003e where i is the position in the list. Automatically fetches some extra data needed in order to compute the first value.\n- \"percent_change\" - Replace every value V\u003csub\u003ei\u003c/sub\u003e with the percent change of V\u003csub\u003ei-1\u003c/sub\u003e and V\u003csub\u003ei\u003c/sub\u003e ( (V\u003csub\u003ei\u003c/sub\u003e / V\u003csub\u003ei-1\u003c/sub\u003e - 1) * 100) where i is the position in the list. Automatically fetches some extra data needed in order to compute the first value.\n\n`aggregation` - the aggregation which is used for the query results.\n\n\n## Available projects\n\nReturns a DataFrame with all the projects available in the Santiment API. Not all\nmetrics will be available for each of the projects.\n\n`slug` is the unique identifier of a project, used in the metrics fetching.\n\n```python\nsan.get(\"projects/all\")\n```\n\nExample result:\n\n```\n                 name             slug ticker   totalSupply\n0              0chain           0chain    ZCN     400000000\n1                  0x               0x    ZRX    1000000000\n2           0xBitcoin            0xbtc  0xBTC      20999984\n3     0xcert Protocol           0xcert    ZXC     500000000\n4              1World           1world    1WO      37219453\n5        AB-Chain RTB     ab-chain-rtb    RTB      27857813\n6             Abulaba          abulaba    AAA     397000000\n7                 AC3              ac3    AC3    80235326.0\n...\n```\n\n\n## Non-standard metrics\n\nHere is a list of metrics that are not part of the returned list of metrics found above.\nThis is due to having different response format and semantics.\n\n### Other Price metrics\n\n#### Marketcap, Price USD, Price BTC and Trading Volume\n\n```python\nsan.get(\n    \"prices\",\n    slug=\"santiment\",\n    from_date=\"2018-06-01\",\n    to_date=\"2018-06-05\",\n    interval=\"1d\"\n)\n```\n#### Open, High, Close, Low Prices, Volume, Marketcap\n\nNotes: \n- This query cannot be batched.\n- The format with separate `slug`/`selector` argument is not supported\n\n```python\nsan.get(\n    \"ohlcv/santiment\",\n    from_date=\"2018-06-01\",\n    to_date=\"2018-06-05\",\n    interval=\"1d\"\n)\n```\n\nExample result:\n\n```python\ndatetime                        openPriceUsd  closePriceUsd  highPriceUsd  lowPriceUsd   volume  marketcap\n2018-06-01 00:00:00+00:00       1.24380        1.27668       1.26599       1.19099       852857  7.736268e+07\n2018-06-02 00:00:00+00:00       1.26136        1.30779       1.27612       1.20958      1242520  7.864724e+07\n2018-06-03 00:00:00+00:00       1.28270        1.28357       1.24625       1.21872      1032910  7.844339e+07\n2018-06-04 00:00:00+00:00       1.23276        1.24910       1.18528       1.18010       617451  7.604326e+07\n```\n\n### Historical Balance\n\nHistorical balance for erc20 token or eth address. Returns the historical balance for a given address in the given interval.\n\n```python\nsan.get(\n    \"historical_balance\",\n    slug=\"santiment\",\n    address=\"0x1f3df0b8390bb8e9e322972c5e75583e87608ec2\",\n    from_date=\"2019-04-18\",\n    to_date=\"2019-04-23\",\n    interval=\"1d\"\n)\n```\n\nExample result:\n\n```\ndatetime                     balance\n2019-04-18 00:00:00+00:00  382338.33\n2019-04-19 00:00:00+00:00  382338.33\n2019-04-20 00:00:00+00:00  382338.33\n2019-04-21 00:00:00+00:00  215664.33\n2019-04-22 00:00:00+00:00  215664.33\n```\n\n### Ethereum Top Transactions\n\nTop ETH transactions for project's team wallets.\n\nAvailable transaction types:\n\n- ALL\n- IN\n- OUT\n\n```python\nsan.get(\n    \"eth_top_transactions\",\n    slug=\"santiment\",\n    from_date=\"2019-04-18\",\n    to_date=\"2019-04-30\",\n    limit=5,\n    transaction_type=\"ALL\"\n)\n```\n\nExample result:\n\n**The result is shortened for convenience**\n\n```\ndatetime                           fromAddress  fromAddressInExchange           toAddress  toAddressInExchange              trxHash      trxValue\n2019-04-29 21:33:31+00:00  0xe76fe52a251c8f...                  False  0x45d6275d9496b...                False  0x776cd57382456a...        100.00\n2019-04-29 21:21:18+00:00  0xe76fe52a251c8f...                  False  0x468bdccdc334f...                False  0x848414fb5c382f...         40.95\n2019-04-19 14:14:52+00:00  0x1f3df0b8390bb8...                  False  0xd69bc0585e05e...                False  0x590512e1f1fbcf...         19.48\n2019-04-19 14:09:58+00:00  0x1f3df0b8390bb8...                  False  0x723fb5c14eaff...                False  0x78e0720b9e72d1...         15.15\n```\n\n### Ethereum Spent Over Time\n\nETH spent for each interval from the project's team wallet and time period\n\n```python\nsan.get(\n    \"eth_spent_over_time\",\n    slug=\"santiment\",\n    from_date=\"2019-04-18\",\n    to_date=\"2019-04-23\",\n    interval=\"1d\"\n)\n```\n\nExample result:\n\n```\ndatetime                    ethSpent\n2019-04-18 00:00:00+00:00   0.000000\n2019-04-19 00:00:00+00:00  34.630284\n2019-04-20 00:00:00+00:00   0.000000\n2019-04-21 00:00:00+00:00   0.000158\n2019-04-22 00:00:00+00:00   0.000000\n```\n\n### Token Top Transactions\n\nTop transactions for the token of a given project\n\n```python\nsan.get(\n    \"token_top_transactions\",\n    slug=\"santiment\",\n    from_date=\"2019-04-18\",\n    to_date=\"2019-04-30\",\n    limit=5\n)\n```\n\nExample result:\n\n**The result is shortened for convenience**\n\n```\ndatetime                           fromAddress  fromAddressInExchange           toAddress  toAddressInExchange              trxHash      trxValue\n2019-04-21 13:51:59+00:00  0x1f3df0b8390bb8...                  False  0x5eaae5e949952...                False  0xdbced935b09dd0...  166674.00000\n2019-04-28 07:43:38+00:00  0x0a920bfdf7f977...                  False  0x868074aab18ea...                False  0x5f2214d34bcdc3...   33181.82279\n2019-04-28 07:53:32+00:00  0x868074aab18ea3...                  False  0x876eabf441b2e...                 True  0x90bd286da38a2b...   33181.82279\n2019-04-26 14:38:45+00:00  0x876eabf441b2ee...                   True  0x76af586d041d6...                False  0xe45b86f415e930...   28999.64023\n2019-04-30 15:17:28+00:00  0x876eabf441b2ee...                   True  0x1f4a90043cf2d...                False  0xc85892b9ef8c64...   20544.42975\n```\n\n### Top Transfers\n\nTop transfers for the token of a given project, ``address`` and ``transaction_type`` arguments can be added as well, in the form of a key-value pair. The ``transaction_type`` parameter can have one of these three values: ``ALL``, ``OUT``, ``IN``.\n\n```python\nsan.get(\n    \"top_transfers\",\n    slug=\"santiment\",\n    from_date=\"utc_now-30d\",\n    to_date=\"utc_now\",\n)\n```\n\n**The result is shortened for convenience**\n\nExample result:\n```\n                          fromAddress   toAddress     trxHash       trxValue\ndatetime                                                                                                                                                                                                                          \n2021-06-17 00:16:26+00:00  0xa48df...  0x876ea...  0x62a56...  136114.069733\n2021-06-17 00:10:05+00:00  0xbd3c2...  0x876ea...  0x732a5...  117339.779890\n2021-06-19 21:36:03+00:00  0x59646...  0x0d45b...  0x5de31...  112336.882707\n...\n```\n\n```python\nsan.get(\n    \"top_transfers\",\n    slug=\"santiment\",\n    address=\"0x26e068650ae54b6c1b149e1b926634b07e137b9f\",\n    transaction_type=\"ALL\",\n    from_date=\"utc_now-30d\",\n    to_date=\"utc_now\",\n)\n```\n\nExample result:\n```\n                          fromAddress  toAddress    trxHash   trxValue\ndatetime                                                                                                                                                                                        \n2021-06-13 09:14:01+00:00  0x26e06...  0xfd3d...  0x4af6...  69854.528\n2021-06-13 09:13:01+00:00  0x876ea...  0x26e0...  0x18c1...  69854.528\n2021-06-14 08:54:52+00:00  0x876ea...  0x26e0...  0xdceb...  59920.591\n...\n```\n\n### Emerging Trends\n\nEmerging trends for a given period of time. \n\n```python\nsan.get(\n    \"emerging_trends\",\n    from_date=\"2019-07-01\",\n    to_date=\"2019-07-02\",\n    interval=\"1d\",\n    size=5\n)\n```\n\nExample result:\n\n```\ndatetime                        score    word\n2019-07-01 00:00:00+00:00  375.160034    lnbc\n2019-07-01 00:00:00+00:00  355.323281    dent\n2019-07-01 00:00:00+00:00  268.653820    link\n2019-07-01 00:00:00+00:00  231.721809  shorts\n2019-07-01 00:00:00+00:00  206.812798     btt\n2019-07-02 00:00:00+00:00  209.343752  bounce\n2019-07-02 00:00:00+00:00  135.412811    vidt\n2019-07-02 00:00:00+00:00  116.842801     bat\n2019-07-02 00:00:00+00:00   98.517600  bottom\n2019-07-02 00:00:00+00:00   89.309975   haiku\n```\n\n## Extras\n\nTake a look at the [examples](/examples/extras) folder.\n\n## Development\n\nIt is recommended to use [pipenv](https://github.com/pypa/pipenv) for managing your local environment.\n\nSetup project:\n\n```bash\npipenv install\n```\n\nInstall main dependencies:\n\n```bash\npipenv run pip install -e .\n```\n\nInstall dev dependencies:\n\n```bash\npipenv run pip install -e '.[dev]'\n```\n\nInstall extra dependencies:\n\n```bash\npipenv run pip install -e '.[extras]'\n```\n\nRunning tests:\n```bash\npipenv run pytest\n```\n\nRunning integration tests:\n```bash\npipenv run pytest -m integration\n```\n\n## Running tests\n\n```bash\npytest\n```\n\n## Running integration tests\n\n```bash\npytest -m integration\n```\n\n## Linting\n\n```bash\npip install '.[dev]'\n```\nor just\n\n```bash\npip install ruff\n```\n\n```bash\nruff check\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsantiment%2Fsanpy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsantiment%2Fsanpy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsantiment%2Fsanpy/lists"}