{"id":28379390,"url":"https://github.com/bitquery/documentation","last_synced_at":"2026-02-08T12:32:31.090Z","repository":{"id":119820739,"uuid":"573796552","full_name":"bitquery/documentation","owner":"bitquery","description":"API system documentation","archived":false,"fork":false,"pushed_at":"2022-12-06T03:11:54.000Z","size":325,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-06-23T10:50:57.420Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bitquery.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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,"zenodo":null}},"created_at":"2022-12-03T13:13:39.000Z","updated_at":"2024-06-19T23:52:11.000Z","dependencies_parsed_at":"2023-06-03T06:45:26.207Z","dependency_job_id":null,"html_url":"https://github.com/bitquery/documentation","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/bitquery/documentation","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitquery%2Fdocumentation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitquery%2Fdocumentation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitquery%2Fdocumentation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitquery%2Fdocumentation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bitquery","download_url":"https://codeload.github.com/bitquery/documentation/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitquery%2Fdocumentation/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268618174,"owners_count":24279241,"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","status":"online","status_checked_at":"2025-08-03T02:00:12.545Z","response_time":2577,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2025-05-30T02:38:18.585Z","updated_at":"2026-02-08T12:32:26.055Z","avatar_url":"https://github.com/bitquery.png","language":null,"readme":"\n# Bitquery API System Overview\nDescription of the information flow and high level system\ndesign for the bitquery software as a service API system.\n\n## Table of Contents\n\n- [Summary](#summary)\n- [Functionality](#functionality)\n- [Structure](#structure)\n- [Accounts](#accounts)\n- [Teams](#teams)\n- [Billing](#billing)\n- [GraphQL API](#graphql-api)\n- [Data Warehouse](#data-warehouse)\n- [Service Quality](#service-quality)\n- [Support](#support)\n\n## Summary\nThe Bitquery API system is a software as a service that allows users to create, manage, and execute queries to retrieve blockchain data from various networks in a unified way. The system consists of a frontend, which is an integrated development environment ([IDE](https://graphql.bitquery.io/)) accessed through a web browser, and a backend that consists of server programs and databases. Users can create accounts and generate unique API keys to authenticate and authorize themselves when executing queries. Users can also save queries for future use and create teams to share queries and billing plans. The system uses a credit-based billing system, with different plans offering different amounts of credits that can be used to execute queries.\n\n## Functionality\n\nBitquery API system is intended to create, manage and execute queries to the blockchain on-\nchain data of many networks in a unified way.\n\nUsers of Bitquery API are people and organisations, who needs to query the blockchain data.\nBitquery provides the tools (IDE and explorer) which help to build and execute queries manually\nand analyse the results. When queries are built, they can be embedded in any external system\nbuilt on any programming language to be executed in an automated way.\n\n## Structure\n\n![bitquery_diagram drawio](https://user-images.githubusercontent.com/82739614/205796686-19b01680-1c8c-4ebe-ad68-56ee4246cee0.png)\n\nAs the diagram shows, the system consists of the frontend part, executed in user’s browser\n(shown on the left) and the backend part (shown on the right).\n\nFrontend is the Integrated development environment ([IDE](https://graphql.bitquery.io/)), the Javascript application, executed\nin user’s browser. It is accessed by URL https://graphql.bitquery.io using any modern browser\n(Chrome recommended).\n\nBackend part is a set of server programs and databases, deployed in Bitquery premises (rented\nfrom a number of datacenter around the world). Most of the backend components are deployed\nas a cluster for performance and redundancy. The primary functionality of the backend system is\nto execute user queries in the data warehouse, storing blockchain data.\n\n## Accounts\n\nAccounts are created by users of the system using email / password pair. After registration,\nunique secret API key is generated. API key is a secret, associated with the account, used to\nauthenticate and authorise in GraphQL server.\n\nAPI key is used every time when user execute queries, be it using IDE or programmatically.\nWithout API keys, user is getting HTTP 401/403 errors.\n\nUser can save queries for the future use in the account database. When saving a query, user can\nselect to save the query privately (visible only to himself and to members of his team) or publicly\n(visible to everyone). When saved, queries are assigned unique URLs and set of tags for ease of\nsearch.\n\n## Teams\n\nUsers can invite other users inside their teams. Team members shares the same set of private\nqueries, and having single billing plan. One user in a team is an administrator, who invite other\nteam members, can add and remove them. Administrator manages billing for the whole team and\npays for the paid plans for the team if necessary.\n\nTeam have the common:\n\n1. Set of private queries. All queries created in team, visible to all members of the team;\n2. Billing plan. Administrator pays for the plan and managing billing information;\n\nWhen user exits the team (removed by administrator or exit by his own) he looses the access to\nthe other team member queries. However the queries that he created as private, remains visible to\nthis user. Also the removed user switches to own billing plan.\n\nUser can join and leave teams at any point of time. His private queries automatically appear\nvisible to the team when joining the new team.\n\nTeams are appropriate in the following situations:\n\n- Organisation or company set up the team for the users of Bitquery IDE and GraphQL API. One\nuser is the administrator, assigned from the organisation;\n- Project team, including temporary projects. The team can be formed to collectively work on the\nset of queries to review and reuse the team queries.\n\n## Billing\n\nBilling tariffs defined at [Bitquery Pricing](https://bitquery.io/pricing) are applied on per-account basis. If account is\nadministrator of the team, the billing plan applied to all members of the team. Plan applied by\ncalendar month period. Starting from the period, certain amount of credits are defined to be spent\nduring this period. When these credits spent, GraphQL server stops serving requests with user\nAPI key. User then can buy additional credits for existing period, and buy the new periods in the\nfuture. Note that the current plan purchased for the current plan may not be changed using IDE,\nbut you can ask Bitquery to do that of you applying support ticket.\n\nCredit purchased for the billing period define the number of points that the user or the team may\nspent in the given billing period. Point are calculated by GraphQL server for every request, using\nthe Statistics Database. This database stores the metrics of the request as they are reported from\nserver(s), executing a given query. Metrics represent actual resources used, such as memory, disk\nI/O bytes, network traffic and others. To calculate count of points, metrics are summed up using\nnormalising coefficients. Coefficients are defined in a way, that results in the average consumption\nof 1 point for simple queries. Some queries may consume less than 1 point, some much more\nthan one.\n\nTo calculate the points consumed by queries, statistics database stores all metrics for every\nquery. Some queries are executed on many servers simultaneously, in this case the metrics are\nsummed up. Periodically the system queries statistics database to get aggregated point count\nfrom the beginning of the billing period. If this count exceeds the count of the credits purchased,\nthe access to the system is automatically turned off.\n\n## GraphQL API\n\nInteraction with the backend part is executed via single [GraphQL endpoint](https://graphql.bitquery.io) using HTTP POST requests. Note that this endpoint URL is the same as for\nthe IDE, the difference only in HTTP method used.\n\nThe endpoint is served by a cluster of GraphQL servers, executing the following logic when\nexecuting the request:\n\n1. Determine if the API key is passed in HTTP X-API-KEY header. Find the account owing this\nAPI key and determine if the current billing period did not consume all credits yet. All these\nactions must be successful, otherwise the error is returned\n\n2. Convert GraphQL query to a set of SQL queries to database and execute them. Note that one\nGraphQL query can embed many different entities, and each of them typically require separate\nSQL query to the database. SQL queries are distributed to the data warehouse cluster. After\nquery is executed, results are converted to JSON and returned to the user.\n\n3. Side effect from the query execution is the records for all metrics as resources, consumed\nfrom servers, in statistics database. This process happens in parallel with the query execution\nand does not affect it directly\n\n## Data Warehouse\n\nData warehouse stores the blockchain data, populated in real time from the set of blockchain\nnodes. Schemas for different blockchains are different, with the dedicated set of tables, optimised\nto be used for specific queries. If GraphQL query hits the table with appropriate ordering, it will be\nexecuted fast, and as a result, consume less points. GraphQL server tries to optimise SQL queries\nselecting the table most appropriate for specific request.\n\nTables are deployed on a cluster of servers, and a particular server is selected to execute the\nquery based on availability and the load on specific server.\n\n## Service Quality\n\nBitquery system considers the following factors constituting quality for users:\n\n1. Availability of the service, meaning that a query an be executed in a reasonable time and get\nproper results\n\n2. Correctness and actuality of the data. The latest data from the blockchain nodes must be\nrecorded into the data warehouse with a reasonable delay. No data must missing or recorded\nas duplicate, etc.\n\n3. Performance of the system, defined by the query execution time, number of queries\nexecuted per second (potentially concurrent) and lack of errors, related to the high load\n\n[Monitoring page](https://graphql.bitquery.io/user/system_status) shows the current status of\nservice quality based on these criteria.\n\n## Support\n\nSupport is provided in a request-response manner and support tickets by the following channels:\n\n1) [Support Ticket System](https://support.bitquery.io/hc/en-us/requests/new)\n2) [Telegram Channel](https://t.me/Bloxy_info) \n3) [Discord Server](https://discord.com/invite/vzHfp7usRk)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitquery%2Fdocumentation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbitquery%2Fdocumentation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitquery%2Fdocumentation/lists"}