Cardano Cardano » Utilities API
The Cardano » Utilities API from Cardano — 3 operation(s) for cardano » utilities.
OpenAPI Specification
openapi: 3.0.3
info:
version: 0.1.89
title: Blockfrost.io ~ API Documentation Cardano » Accounts Cardano » Utilities API
x-logo:
url: https://staging.blockfrost.io/images/logo.svg
altText: Blockfrost
contact:
name: Blockfrost Team
url: https://blockfrost.io
email: contact@blockfrost.io
license:
name: MIT
url: https://opensource.org/licenses/MIT
termsOfService: https://blockfrost.io/terms
description: "Blockfrost is an API as a service that allows users to interact with the Cardano blockchain, Midnight blockchain, and parts of their ecosystems.\n\n## Tokens\n\nAfter signing up on https://blockfrost.io, a `project_id` token is automatically generated for each project.\nHTTP header of your request MUST include this `project_id` in order to authenticate against Blockfrost servers.\n\n## Available networks\n\nAt the moment, you can use the following networks. Please, note that each network has its own `project_id`.\n\n<table>\n <tbody>\n <tr>\n <td>\n <b>Network</b>\n </td>\n <td>\n <b>Endpoint</b>\n </td>\n </tr>\n <tr>\n <td>Cardano mainnet</td>\n <td>\n <code>https://cardano-mainnet.blockfrost.io/api/v0</code>\n </td>\n </tr>\n <tr>\n <td>Cardano preprod</td>\n <td>\n <code>https://cardano-preprod.blockfrost.io/api/v0</code>\n </td>\n </tr>\n <tr>\n <td>Cardano preview</td>\n <td>\n <code>https://cardano-preview.blockfrost.io/api/v0</code>\n </td>\n </tr>\n <tr>\n <td>Midnight mainnet</td>\n <td>\n <code>https://midnight-mainnet.blockfrost.io/api/v0</code>\n </td>\n </tr>\n <tr>\n <td>InterPlanetary File System</td>\n <td>\n <code>https://ipfs.blockfrost.io/api/v0</code>\n </td>\n </tr>\n </tbody>\n</table>\n\n## Concepts\n\n* All endpoints return either a JSON object or an array.\n* Data is returned in *ascending* (oldest first, newest last) order, if not stated otherwise.\n * You might use the `?order=desc` query parameter to reverse this order.\n* By default, we return 100 results at a time. You have to use `?page=2` to list through the results.\n* All time and timestamp related fields (except `server_time`) are in seconds of UNIX time.\n* All amounts are returned in Lovelaces, where 1 ADA = 1 000 000 Lovelaces.\n* Addresses, accounts and pool IDs are in Bech32 format.\n* All values are case sensitive.\n* All hex encoded values are lower case.\n* Examples are not based on real data. Any resemblance to actual events is purely coincidental.\n* We allow to upload files up to 100MB of size to IPFS. This might increase in the future.\n* Only pinned IPFS files are counted towards the IPFS quota.\n* Non-pinned IPFS files are subject to regular garbage collection and will be removed unless pinned.\n* We allow maximum of 100 queued pins per IPFS user.\n\n## Errors\n\n### HTTP Status codes\n\nThe following are HTTP status code your application might receive when reaching Blockfrost endpoints and\nit should handle all of these cases.\n\n* HTTP `400` return code is used when the request is not valid.\n* HTTP `402` return code is used when the projects exceed their daily request limit.\n* HTTP `403` return code is used when the request is not authenticated.\n* HTTP `404` return code is used when the resource doesn't exist.\n* HTTP `418` return code is used when the user has been auto-banned for flooding too much after previously receiving error code `402` or `429`.\n* HTTP `425` return code is used in Cardano networks, when the user has submitted a transaction when the mempool is already full, not accepting new txs straight away.\n* HTTP `425` return code is used in IPFS network, when the user has submitted a pin when the pin queue is already full, not accepting new pins straight away.\n* HTTP `429` return code is used when the user has sent too many requests in a given amount of time and therefore has been rate-limited.\n* HTTP `500` return code is used when our endpoints are having a problem.\n\n### Error codes\n\nAn internal error code number is used for better indication of the error in question. It is passed using the following payload.\n\n```json\n{\n \"status_code\": 403,\n \"error\": \"Forbidden\",\n \"message\": \"Invalid project token.\"\n}\n```\n## Limits\n\nThere are two types of limits we are enforcing:\n\nThe first depends on your plan and is the number of request we allow per day. We defined the day from midnight to midnight of UTC time.\n\nThe second is rate limiting. We limit an end user, distinguished by IP address, to 10 requests per second. On top of that, we allow\neach user to send burst of 500 requests, which cools off at rate of 10 requests per second. In essence, a user is allowed to make another\nwhole burst after (currently) 500/10 = 50 seconds. E.g. if a user attempts to make a call 3 seconds after whole burst, 30 requests will be processed.\nWe believe this should be sufficient for most of the use cases. If it is not and you have a specific use case, please get in touch with us, and\nwe will make sure to take it into account as much as we can.\n\n## SDKs\n\nWe support a number of SDKs that will help you in developing your application on top of Blockfrost.\n\n<table>\n <tbody>\n <tr>\n <td><b>Programming language</b></td>\n <td><b>SDK</b></td>\n </tr>\n <tr>\n <td>JavaScript</td>\n <td>\n <a href=\"https://github.com/blockfrost/blockfrost-js\">blockfrost-js</a>\n </td>\n </tr>\n <tr>\n <td>Haskell</td>\n <td>\n <a href=\"https://github.com/blockfrost/blockfrost-haskell\">blockfrost-haskell</a>\n </td>\n </tr>\n <tr>\n <td>Python</td>\n <td>\n <a href=\"https://github.com/blockfrost/blockfrost-python\">blockfrost-python</a>\n </td>\n </tr>\n <tr>\n <td>Rust</td>\n <td>\n <a href=\"https://github.com/blockfrost/blockfrost-rust\">blockfrost-rust</a>\n </td>\n </tr>\n <tr>\n <td>Golang</td>\n <td>\n <a href=\"https://github.com/blockfrost/blockfrost-go\">blockfrost-go</a>\n </td>\n </tr>\n <tr>\n <td>Ruby</td>\n <td>\n <a href=\"https://github.com/blockfrost/blockfrost-ruby\">blockfrost-ruby</a>\n </td>\n </tr>\n <tr>\n <td>Java</td>\n <td>\n <a href=\"https://github.com/blockfrost/blockfrost-java\">blockfrost-java</a>\n </td>\n </tr>\n <tr>\n <td>Scala</td>\n <td>\n <a href=\"https://github.com/blockfrost/blockfrost-scala\">blockfrost-scala</a>\n </td>\n </tr>\n <tr>\n <td>Swift</td>\n <td>\n <a href=\"https://github.com/blockfrost/blockfrost-swift\">blockfrost-swift</a>\n </td>\n </tr>\n <tr>\n <td>Kotlin</td>\n <td>\n <a href=\"https://github.com/blockfrost/blockfrost-kotlin\">blockfrost-kotlin</a>\n </td>\n </tr>\n <tr>\n <td>Elixir</td>\n <td>\n <a href=\"https://github.com/blockfrost/blockfrost-elixir\">blockfrost-elixir</a>\n </td>\n </tr>\n <tr>\n <td>.NET</td>\n <td>\n <a href=\"https://github.com/blockfrost/blockfrost-dotnet\">blockfrost-dotnet</a>\n </td>\n </tr>\n <tr>\n <td>Arduino</td>\n <td>\n <a href=\"https://github.com/blockfrost/blockfrost-arduino\">blockfrost-arduino</a>\n </td>\n </tr>\n <tr>\n <td>PHP</td>\n <td>\n <a href=\"https://github.com/blockfrost/blockfrost-php\">blockfrost-php</a>\n </td>\n </tr>\n <tr>\n <td>Crystal</td>\n <td>\n <a href=\"https://github.com/blockfrost/blockfrost-crystal\">blockfrost-crystal</a>\n </td>\n </tr>\n </tbody>\n</table>\n\n\n## Midnight API\n\n\nThe Midnight Indexer API exposes a GraphQL API that enables clients to query and subscribe to blockchain data — blocks, transactions, contracts, and wallet-related events — indexed from the Midnight blockchain.\n\nAvailable networks: `mainnet`, `preprod`, `preview`\n\n| Service | URL | Protocol |\n|---------|-----|----------|\n| **Indexer HTTP API** | `https://midnight-{network}.blockfrost.io/api/v0` | HTTP POST (GraphQL) |\n| **Indexer Subscriptions API** | `wss://midnight-{network}.blockfrost.io/api/v0/ws` | WebSocket |\n| **Node RPC** | `https://rpc.midnight-{network}.blockfrost.io` | JSON-RPC |\n\n\nFor the full documentation — queries, mutations, subscriptions, authentication options, and examples — see the Midnight GraphQL API Reference:\n\n[](./midnight/)\n"
servers:
- url: https://cardano-mainnet.blockfrost.io/api/v0
description: Cardano Mainnet network
- url: https://cardano-preprod.blockfrost.io/api/v0
description: Cardano Preprod network
- url: https://cardano-preview.blockfrost.io/api/v0
description: Cardano Preview network
- url: https://localhost:3000
description: local
security:
- project_id: []
tags:
- name: Cardano » Utilities
paths:
/utils/addresses/xpub/{xpub}/{role}/{index}:
get:
tags:
- Cardano » Utilities
summary: Derive an address
description: Derive Shelley address from an xpub
parameters:
- in: path
name: xpub
required: true
schema:
type: string
description: Hex xpub
example: d507c8f866691bd96e131334c355188b1a1d0b2fa0ab11545075aab332d77d9eb19657ad13ee581b56b0f8d744d66ca356b93d42fe176b3de007d53e9c4c4e7a
- in: path
name: role
required: true
schema:
type: integer
description: Account role
example: 0
- in: path
name: index
required: true
schema:
type: integer
description: Address index
example: 2
responses:
'200':
description: Return derivated Shelley address
content:
application/json:
schema:
$ref: '#/components/schemas/utils_addresses_xpub'
'400':
$ref: '#/components/responses/400'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'418':
$ref: '#/components/responses/418'
'429':
$ref: '#/components/responses/429'
'500':
$ref: '#/components/responses/500'
/utils/txs/evaluate:
post:
tags:
- Cardano » Utilities
summary: Submit a transaction for execution units evaluation
description: "Submit an already serialized transaction to evaluate how much execution units it requires.\n\n<p>\n <span class=\"hosted\">Hosted</span> Endpoint only available for hosted variant.\n</p>\n"
parameters:
- in: header
name: Content-Type
required: true
schema:
type: string
enum:
- application/cbor
- in: query
name: version
required: false
schema:
type: number
default: 5
description: 'Optional parameter to specify the version of the Ogmios service to use. Default is `5`. Set to `6` to use Ogmios version 6.
'
x-codeSamples:
- lang: Shell
label: cURL
source: "# Assuming `tx.data` is a CBOR serialized transaction on the file-system.\n# (encoded using base16 or base64)\ncurl \"https://cardano-mainnet.blockfrost.io/api/v0/utils/txs/evaluate\" \\\n -X POST \\\n -H \"Content-Type: application/cbor\" \\\n -H \"project_id: $PROJECT_ID\" \\\n --data @./tx.data\n"
requestBody:
description: 'The transaction to submit, serialized in CBOR.
'
required: true
content:
application/cbor:
schema:
type: string
description: 'The transaction to submit, serialized in CBOR.
'
example: '83a400818258208911f640d452c3be4ff3d89db63b41ce048c056951286e2e28bbf8a51588ab44000181825839009493315cd92eb5d8c4304e67b7e16ae36d61d34502694657811a2c8e32c728d3861e164cab28cb8f006448139c8f1740ffb8e7aa9e5232dc1a10b2531f021a00029519075820cb798b0bce50604eaf2e0dc89367896b18f0a6ef6b32b57e3c9f83f8ee71e608a1008182582073fea80d424276ad0978d4fe5310e8bc2d485f5f6bb3bf87612989f112ad5a7d5840c40425229749a9434763cf01b492057fd56d7091a6372eaa777a1c9b1ca508c914e6a4ee9c0d40fc10952ed668e9ad65378a28b149de6bd4204bd9f095b0a902a11907b0a1667469636b657281a266736f757263656b736f757263655f6e616d656576616c7565736675676961742076656e69616d206d696e7573
'
responses:
'200':
description: "<p>\n <div class=\"custom-paragraph\">\n Returns result of EvaluateTx function from Ogmios see <a class=\"custom-link\" href=\"https://ogmios.dev/mini-protocols/local-tx-submission/#evaluatetx\">EvaluateTx</a>\n and<a href=\"https://ogmios.dev/http-api/\"> API reference (EvaluateTxResponse)</a> for related errors.\n </div>\n</p>\n"
content:
application/json:
schema:
type: object
additionalProperties: true
'400':
$ref: '#/components/responses/400'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'418':
$ref: '#/components/responses/418'
'425':
$ref: '#/components/responses/425'
'429':
$ref: '#/components/responses/429'
'500':
$ref: '#/components/responses/500'
/utils/txs/evaluate/utxos:
post:
tags:
- Cardano » Utilities
summary: Submit a transaction for execution units evaluation (additional UTXO set)
description: "Submit a JSON payload with transaction CBOR and additional UTXO set to evaluate how much execution units it requires.\n\n<p>\n <span class=\"hosted\">Hosted</span> Endpoint only available for hosted variant.\n</p>\n"
parameters:
- in: header
name: Content-Type
required: true
schema:
type: string
enum:
- application/json
- in: query
name: version
required: false
schema:
type: number
default: 5
description: 'Optional parameter to specify the version of the Ogmios service to use. Default is `5`. Set to `6` to use Ogmios version 6.
'
requestBody:
description: JSON payload
required: true
content:
application/json:
schema:
type: object
properties:
cbor:
type: string
description: Transaction CBOR (encoded using base64 or base16).
additionalUtxoSet:
type: array
description: Additional UTXO as an array of tuples [TxIn, TxOut]. See https://ogmios.dev/mini-protocols/local-tx-submission/#additional-utxo-set.
items:
type: array
minItems: 2
maxItems: 2
items:
anyOf:
- type: object
description: TxIn
properties:
txId:
type: string
description: Transaction hash for the input
index:
type: number
description: Index of the output within the transaction
- type: object
description: TxOut
properties:
address:
type: string
description: Output address
value:
type: object
properties:
coins:
type: number
description: Lovelace amount
assets:
type: object
description: Assets amount
additionalProperties:
type: number
required:
- coins
datum_hash:
type: string
datum:
type: object
additionalProperties: true
script:
type: object
additionalProperties: true
required:
- address
- value
required:
- cbor
x-codeSamples:
- lang: Shell
label: cURL
source: "# Assuming TxCbor is a CBOR serialized transaction encoded using base16 or base64\n# For a structure of additional UTXO set see https://ogmios.dev/mini-protocols/local-tx-submission/#additional-utxo-set\ncurl \"https://cardano-mainnet.blockfrost.io/api/v0/utils/txs/evaluate/utxos\" \\\n -X POST \\\n -H \"Content-Type: application/json\" \\\n -H \"project_id: $PROJECT_ID\" \\\n -d '{\"cbor\":\"<TxCbor>\",\"additionalUtxoSet\":[[<TxIn>, <TxOut>]]}'\n"
responses:
'200':
description: "<p>\n <div class=\"custom-paragraph\">\n Returns result of EvaluateTx function from Ogmios see <a class=\"custom-link\" href=\"https://ogmios.dev/mini-protocols/local-tx-submission/#evaluatetx\">EvaluateTx</a>\n and<a href=\"https://ogmios.dev/api/\"> API reference (EvaluateTxResponse)</a> for related errors.\n </div>\n</p>\n"
content:
application/json:
schema:
type: object
additionalProperties: true
'400':
$ref: '#/components/responses/400'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'418':
$ref: '#/components/responses/418'
'425':
$ref: '#/components/responses/425'
'429':
$ref: '#/components/responses/429'
'500':
$ref: '#/components/responses/500'
components:
responses:
'500':
description: Internal Server Error
content:
application/json:
schema:
type: object
properties:
status_code:
type: integer
example: 500
error:
type: string
example: Internal Server Error
message:
type: string
example: An unexpected response was received from the backend.
required:
- error
- message
- status_code
'425':
description: Mempool is already full, not accepting new txs straight away
content:
application/json:
schema:
type: object
properties:
status_code:
type: integer
example: 425
error:
type: string
example: Mempool Full
message:
type: string
example: Mempool is full, please try resubmitting again later.
required:
- error
- message
- status_code
'429':
description: Usage limit reached
content:
application/json:
schema:
type: object
properties:
status_code:
type: integer
example: 429
error:
type: string
example: Project Over Limit
message:
type: string
example: Usage is over limit.
required:
- error
- message
- status_code
'403':
description: Authentication secret is missing or invalid
content:
application/json:
schema:
type: object
properties:
status_code:
type: integer
example: 403
error:
type: string
example: Forbidden
message:
type: string
example: Invalid project token.
required:
- error
- message
- status_code
'404':
description: Component not found
content:
application/json:
schema:
type: object
properties:
status_code:
type: integer
example: 404
error:
type: string
example: Not Found
message:
type: string
example: The requested component has not been found.
required:
- error
- message
- status_code
'400':
description: Bad request
content:
application/json:
schema:
type: object
properties:
status_code:
type: integer
example: 400
error:
type: string
example: Bad Request
message:
type: string
example: Backend did not understand your request.
required:
- error
- message
- status_code
'418':
description: IP has been auto-banned for extensive sending of requests after usage limit has been reached
content:
application/json:
schema:
type: object
properties:
status_code:
type: integer
example: 418
error:
type: string
example: Requested Banned
message:
type: string
example: IP has been auto-banned for flooding.
required:
- error
- message
- status_code
schemas:
utils_addresses_xpub:
type: object
properties:
xpub:
type: string
description: Script hash
role:
type: integer
description: Account role
index:
type: integer
description: Address index
address:
type: string
description: Derived address
required:
- xpub
- role
- index
- address
example:
- xpub: d507c8f866691bd96e131334c355188b1a1d0b2fa0ab11545075aab332d77d9eb19657ad13ee581b56b0f8d744d66ca356b93d42fe176b3de007d53e9c4c4e7a
role: 0
index: 0
address: addr1q90sqnljxky88s0jsnps48jd872p7znzwym0jpzqnax6qs5nfrlkaatu28n0qzmqh7f2cpksxhpc9jefx3wrl0a2wu8q5amen7
securitySchemes:
project_id:
type: apiKey
in: header
name: project_id
description: 'There are multiple token types available based on network you choose
when creating a Blockfrost a project, for a list of token types
see available networks.
'