{"id":22437059,"url":"https://github.com/blockfrost/blockfrost-js","last_synced_at":"2025-04-05T11:07:45.212Z","repository":{"id":37823518,"uuid":"336916358","full_name":"blockfrost/blockfrost-js","owner":"blockfrost","description":"Node.js SDK for the Blockfrost.io API.","archived":false,"fork":false,"pushed_at":"2025-02-07T14:27:12.000Z","size":897881,"stargazers_count":106,"open_issues_count":7,"forks_count":25,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-29T10:05:41.137Z","etag":null,"topics":["api","blockfrost","cardano","ipfs","javascript","nodejs","sdk","typescript"],"latest_commit_sha":null,"homepage":"https://blockfrost.io","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/blockfrost.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.MD","contributing":null,"funding":null,"license":"LICENSE","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":"2021-02-07T23:55:10.000Z","updated_at":"2025-03-07T12:54:31.000Z","dependencies_parsed_at":"2023-01-30T01:31:21.834Z","dependency_job_id":"3d4b634a-a8d4-4f4e-aa58-e2597a4427f0","html_url":"https://github.com/blockfrost/blockfrost-js","commit_stats":null,"previous_names":[],"tags_count":56,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blockfrost%2Fblockfrost-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blockfrost%2Fblockfrost-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blockfrost%2Fblockfrost-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blockfrost%2Fblockfrost-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/blockfrost","download_url":"https://codeload.github.com/blockfrost/blockfrost-js/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247325693,"owners_count":20920714,"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":["api","blockfrost","cardano","ipfs","javascript","nodejs","sdk","typescript"],"created_at":"2024-12-06T00:11:28.996Z","updated_at":"2025-04-05T11:07:45.160Z","avatar_url":"https://github.com/blockfrost.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![master build ci](https://github.com/blockfrost/blockfrost-js/actions/workflows/build.yml/badge.svg?branch=master) [![npm version](https://badge.fury.io/js/%40blockfrost%2Fblockfrost-js.svg)](https://badge.fury.io/js/%40blockfrost%2Fblockfrost-js) ![downloads](https://img.shields.io/npm/dy/@blockfrost/blockfrost-js) \u003cimg src=\"https://github.com/blockfrost/blockfrost-js/blob/master/coverage-badge.svg\" /\u003e \u003ca href=\"https://fivebinaries.com/\"\u003e\u003cimg src=\"https://img.shields.io/badge/made%20by-Five%20Binaries-darkviolet.svg?style=flat-square\" /\u003e\u003c/a\u003e\n\n\u003cimg src=\"https://blockfrost.io/images/logo.svg\" width=\"250\" align=\"right\" height=\"90\"\u003e\n\n# blockfrost-js\n\n\u003cbr/\u003e\n\n\u003cp align=\"center\"\u003e\u003ca href=\"https://blockfrost.io\"\u003eBlockfrost.io\u003c/a\u003e SDK for JavaScript for Node.js.\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#getting-started\"\u003eGetting started\u003c/a\u003e •\n  \u003ca href=\"#installation\"\u003eInstallation\u003c/a\u003e •\n  \u003ca href=\"#usage\"\u003eUsage\u003c/a\u003e •\n  \u003ca href=\"https://github.com/blockfrost/blockfrost-js-examples\" target=\"_blank\"\u003eExamples\u003c/a\u003e •\n  \u003ca href=\"https://github.com/blockfrost/blockfrost-js/wiki/Exports\"\u003eSDK API Reference\u003c/a\u003e\n\u003c/p\u003e\n\u003cbr\u003e\n\n## Getting started\n\nTo use this SDK, you first need to log in to [blockfrost.io](https://blockfrost.io), create your project and retrieve the API token.\n\n\u003cimg src=\"https://i.imgur.com/WoEIYhk.png\" width=\"750\" height=\"400\"\u003e\n\n\u003cbr/\u003e\n\n## Installation\n\nTo run the SDK you need Node.js version 16 and higher. While you may find a way to run it directly in a browser, we don't actively support or provide troubleshooting assistance with this scenario. We recommend setting up your own Node.js backend. Exposing your API keys in a frontend application is almost always a bad idea.\n\nThe SDK is hosted on [npmjs.com](https://www.npmjs.com/package/@blockfrost/blockfrost-js), so you can directly import it using your favorite package manager.\n\n```console\nnpm i @blockfrost/blockfrost-js\n```\n\n```console\nyarn add @blockfrost/blockfrost-js\n```\n\n\u003cbr/\u003e\n\n## Usage\n\nUsing the SDK is pretty straight-forward as you can see from the following examples.\nFor more examples take a look in [blockfrost-js-examples](https://github.com/blockfrost/blockfrost-js-examples) repository.\n\nFor a list of all SDK methods [check out our wiki](https://github.com/blockfrost/blockfrost-js/wiki/Exports).\n\n```ts\nconst Blockfrost = require('@blockfrost/blockfrost-js');\n// import { BlockFrostAPI } from '@blockfrost/blockfrost-js'; // using import syntax\n\nconst API = new Blockfrost.BlockFrostAPI({\n  projectId: 'YOUR API KEY HERE', // see: https://blockfrost.io\n  // For a list of all options see section below\n});\n```\n\n### Options\n\n- `projectId` - `string`, Blockfrost project ID (required)\n- `network` - `string`, Cardano network for given project ID. (optional, default value is derived from the `projectId` itself if possible). Possible values: `mainnet`, `testnet`, `preview`, `preprod`.\n- `rateLimiter` - `boolean` or [`RateLimiterConfig`](https://github.com/blockfrost/blockfrost-js/blob/master/src/utils/limiter.ts#L18=), whether to enable rate limiter that matches [Blockfrost API limits](https://docs.blockfrost.io/#section/Limits) (optional, default `true`). If you have your IP addresses white-listed you may want to disable it. You may also customize rate limiter by passing your own [config object](ttps://github.com/blockfrost/blockfrost-js/blob/master/src/utils/limiter.ts#11).\n- `requestTimeout` - `number`, How long to wait for a request to complete, in milliseconds (optional, default `20000`)\n- `retrySettings` - `RequiredRetryOptions`, customizations for retrying failed request (optional, [for defaults click here](https://github.com/blockfrost/blockfrost-js/blob/master/src/utils/index.ts#L58))\n- `debug` - `boolean`, whether to enable debug logging. It is also possible to enable it by setting environment variable `DEBUG` to `true` (optional, default `false`).\n- `customBackend` - `string`, option to set URL to a non-official backend (optional)\n- `version` - `number`, version of the Blockfrost API (optional, default `0`)\n- `gotOptions` - Additional options to be passed to Got instance. For more details, refer to the [Got Options documentation](https://github.com/sindresorhus/got/blob/main/documentation/2-options.md).\n\n\n## Error handling\n\nBlockfrost Node.js SDK throws 2 types of errors, `BlockfrostServerError` and `BlockfrostClientError`. Each of these errors is extended from the built-in `Error` class, allowing you to properly catch it and handle it in your code.\n\n### `BlockfrostServerError`\n\n`BlockfrostServerError` is an error returned directly by Blockfrost API. The error object's properties are matching [the same format as defined by Blockfrost API](\u003c(https://docs.blockfrost.io/#section/Errors)\u003e), with additional `url` field set to the URL the request was sent to and optional `body` field set to the original body of the error response in cases where the error was not returned by Blockfrost Backend (eg. nginx).\n\n#### Example\n\nBlockfrost API returns 404 Not Found for any resource that does not exist on chain at the moment, even when in theory, it could exist. For more detailed explanation check [Blockfrost developer portal](https://www.blockfrost.dev/docs/support/cardano#querying-address-returns-404-not-found-but-my-address-is-valid).\n\n```ts\n// Example demonstrating catching BlockfrostServerError\ntry {\n  const address = await API.addresses('totallyValidAddress');\n} catch (error) {\n  if (\n    error instanceof Blockfrost.BlockfrostServerError \u0026\u0026\n    error.status_code === 404\n  ) {\n    // address was not used before, but most likely we don't want to throw an error\n    console.log(\"Address is totally empty! But that's ok!\");\n  } else {\n    // rethrow other errors\n    throw error;\n  }\n}\n```\n\n### `BlockfrostClientError`\n\n`BlockfrostClientError` is an error that was NOT returned by a Blockfrost API server. In this case the request has never reached our backends. Most common causes are network-related.\n\nShape of `BlockfrostClientError` object is slightly different from `BlockfrostServerError`. The error has `code` and `message` and optional `url` property to help you investigate the issue.\n\nHere is a small example showcasing the error format:\n\n```json\n{\n  \"code\": \"ENOTFOUND\",\n  \"message\": \"getaddrinfo ENOTFOUND api.blockfrost.io\",\n  \"url\": \"https://cardano-mainnet.blockfrost.io/api/v0/addresses/addr1qxqs59lph(truncated)\"\n}\n```\n\n#### Example\n\n```ts\n// Example demonstrating catching a network-related client error\ntry {\n  const address = await API.addresses('totallyValidAddress');\n} catch (error) {\n  if (error instanceof Blockfrost.BlockfrostClientError) {\n    console.log('Oops, error during sending the request');\n  }\n  // Depending on your use case you may want to rethrow the error\n  throw error;\n}\n```\n\n## Examples\n\nFor more examples take a look in [blockfrost-js-examples](https://github.com/blockfrost/blockfrost-js-examples) repository.\n\nFor a list of all SDK methods [check out our wiki](https://github.com/blockfrost/blockfrost-js/wiki/Exports).\n\n### Cardano\n\n```typescript\nconst Blockfrost = require('@blockfrost/blockfrost-js');\n// import { BlockFrostAPI } from '@blockfrost/blockfrost-js'; // using import syntax\n\nconst API = new Blockfrost.BlockFrostAPI({\n  projectId: 'YOUR API KEY HERE', // see: https://blockfrost.io\n});\n\nasync function runExample() {\n  try {\n    const latestBlock = await API.blocksLatest();\n    const networkInfo = await API.network();\n    const latestEpoch = await API.epochsLatest();\n    const health = await API.health();\n    const address = await API.addresses(\n      'addr1qxqs59lphg8g6qndelq8xwqn60ag3aeyfcp33c2kdp46a09re5df3pzwwmyq946axfcejy5n4x0y99wqpgtp2gd0k09qsgy6pz',\n    );\n    const pools = await API.pools({ page: 1, count: 10, order: 'asc' });\n\n    console.log('pools', pools);\n    console.log('address', address);\n    console.log('networkInfo', networkInfo);\n    console.log('latestEpoch', latestEpoch);\n    console.log('latestBlock', latestBlock);\n    console.log('health', health);\n  } catch (err) {\n    console.log('error', err);\n  }\n}\n\nrunExample();\n```\n\n### IPFS\n\n```typescript\nconst Blockfrost = require('@blockfrost/blockfrost-js');\n// import { BlockFrostIPFS } from '@blockfrost/blockfrost-js'; // using import syntax\n\nconst IPFS = new Blockfrost.BlockFrostIPFS({\n  projectId: 'YOUR IPFS KEY HERE', // see: https://blockfrost.io\n});\n\nasync function runExample() {\n  try {\n    const added = await IPFS.add(`${__dirname}/img.svg`);\n    console.log('added', added);\n\n    const pinned = await IPFS.pin(added.ipfs_hash);\n    console.log('pinned', pinned);\n  } catch (err) {\n    console.log('error', err);\n  }\n}\n\nrunExample();\n```\n\n## Utility functions\n\nBlockfrost SDK exports several utility functions to improve developer experience.\n\n- [deriveAddress](https://github.com/blockfrost/blockfrost-js/wiki/Exports#deriveaddress)\n- [getFingerprint](https://github.com/blockfrost/blockfrost-js/wiki/Exports#getfingerprint)\n- [parseAsset](https://github.com/blockfrost/blockfrost-js/wiki/Exports#parseasset)\n- [verifyWebhookSignature](https://github.com/blockfrost/blockfrost-js/wiki/Exports#verifywebhooksignature)\n\n## Development\n\n### Adding new method\n\n1. Add a code to a corresponding file. e.g. new account method belong to `src/endpoints/api/account/` directory.\n   - add `\u003cmethod\u003eAll` method for endpoints with pagination\n   - update [TSDoc](https://tsdoc.org/) for added method\n2. Add class method to `BlockfrostAPI` object in [src/BlockFrostAPI.ts](src/BlockFrostAPI.ts).\n3. Add unit-test fixture for the added method to [test/fixtures/endpoints.ts](test/fixtures/endpoints.ts)\n4. Regenerate wiki docs\n   - `yarn docs`\n   - push files to Wiki repository `https://github.com/blockfrost/blockfrost-js.wiki.git`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblockfrost%2Fblockfrost-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblockfrost%2Fblockfrost-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblockfrost%2Fblockfrost-js/lists"}