openapi: 3.0.3
info:
version: 0.1.89
title: Blockfrost.io ~ API Documentation Cardano » Accounts Cardano » Addresses 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
\n \n \n | \n Network\n | \n \n Endpoint\n | \n
\n \n | Cardano mainnet | \n \n https://cardano-mainnet.blockfrost.io/api/v0\n | \n
\n \n | Cardano preprod | \n \n https://cardano-preprod.blockfrost.io/api/v0\n | \n
\n \n | Cardano preview | \n \n https://cardano-preview.blockfrost.io/api/v0\n | \n
\n \n | Midnight mainnet | \n \n https://midnight-mainnet.blockfrost.io/api/v0\n | \n
\n \n | InterPlanetary File System | \n \n https://ipfs.blockfrost.io/api/v0\n | \n
\n \n
\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\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 » Addresses
paths:
/addresses/{address}:
get:
tags:
- Cardano » Addresses
summary: Specific address
description: Obtain information about a specific address.
parameters:
- in: path
name: address
required: true
schema:
type: string
description: Bech32 address.
example: addr1qxqs59lphg8g6qndelq8xwqn60ag3aeyfcp33c2kdp46a09re5df3pzwwmyq946axfcejy5n4x0y99wqpgtp2gd0k09qsgy6pz
responses:
'200':
description: Return the address content.
content:
application/json:
schema:
$ref: '#/components/schemas/address_content'
'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'
/addresses/{address}/extended:
get:
tags:
- Cardano » Addresses
summary: Extended information of a specific address
description: 'Obtain extended information about a specific address.
'
parameters:
- in: path
name: address
required: true
schema:
type: string
description: Bech32 address.
example: addr1qxqs59lphg8g6qndelq8xwqn60ag3aeyfcp33c2kdp46a09re5df3pzwwmyq946axfcejy5n4x0y99wqpgtp2gd0k09qsgy6pz
responses:
'200':
description: Return the address content.
content:
application/json:
schema:
$ref: '#/components/schemas/address_content_extended'
'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'
/addresses/{address}/total:
get:
tags:
- Cardano » Addresses
summary: Address details
description: Obtain details about an address.
parameters:
- in: path
name: address
required: true
schema:
type: string
description: Bech32 address.
example: addr1qxqs59lphg8g6qndelq8xwqn60ag3aeyfcp33c2kdp46a09re5df3pzwwmyq946axfcejy5n4x0y99wqpgtp2gd0k09qsgy6pz
responses:
'200':
description: Return the Address details.
content:
application/json:
schema:
$ref: '#/components/schemas/address_content_total'
'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'
/addresses/{address}/utxos:
get:
tags:
- Cardano » Addresses
summary: Address UTXOs
description: UTXOs of the address.
parameters:
- in: path
name: address
required: true
schema:
type: string
description: Bech32 address.
example: addr1qxqs59lphg8g6qndelq8xwqn60ag3aeyfcp33c2kdp46a09re5df3pzwwmyq946axfcejy5n4x0y99wqpgtp2gd0k09qsgy6pz
- in: query
name: count
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 100
description: The number of results displayed on one page.
- in: query
name: page
required: false
schema:
type: integer
minimum: 1
maximum: 21474836
default: 1
description: The page number for listing the results.
- in: query
name: order
required: false
schema:
type: string
enum:
- asc
- desc
default: asc
description: 'The ordering of items from the point of view of the blockchain,
not the page listing itself. By default, we return oldest first, newest last.
'
responses:
'200':
description: Return the address content
content:
application/json:
schema:
$ref: '#/components/schemas/address_utxo_content'
'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'
/addresses/{address}/utxos/{asset}:
get:
tags:
- Cardano » Addresses
summary: Address UTXOs of a given asset
description: UTXOs of the address.
parameters:
- in: path
name: address
required: true
schema:
type: string
description: Bech32 address.
example: addr1qxqs59lphg8g6qndelq8xwqn60ag3aeyfcp33c2kdp46a09re5df3pzwwmyq946axfcejy5n4x0y99wqpgtp2gd0k09qsgy6pz
- in: path
name: asset
required: true
schema:
type: string
description: Concatenation of the policy_id and hex-encoded asset_name
example: b0d07d45fe9514f80213f4020e5a61241458be626841cde717cb38a76e7574636f696e
- in: query
name: count
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 100
description: The number of results displayed on one page.
- in: query
name: page
required: false
schema:
type: integer
minimum: 1
maximum: 21474836
default: 1
description: The page number for listing the results.
- in: query
name: order
required: false
schema:
type: string
enum:
- asc
- desc
default: asc
description: 'The ordering of items from the point of view of the blockchain,
not the page listing itself. By default, we return oldest first, newest last.
'
responses:
'200':
description: Return the address content
content:
application/json:
schema:
$ref: '#/components/schemas/address_utxo_content'
'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'
/addresses/{address}/txs:
get:
deprecated: true
tags:
- Cardano » Addresses
summary: Address txs
description: Transactions on the address.
parameters:
- in: path
name: address
required: true
schema:
type: string
description: Bech32 address.
example: addr1qxqs59lphg8g6qndelq8xwqn60ag3aeyfcp33c2kdp46a09re5df3pzwwmyq946axfcejy5n4x0y99wqpgtp2gd0k09qsgy6pz
- in: query
name: count
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 100
description: The number of transactions per page.
- in: query
name: page
required: false
schema:
type: integer
minimum: 1
maximum: 21474836
default: 1
description: The page number for listing the results.
- in: query
name: order
required: false
schema:
type: string
enum:
- asc
- desc
default: asc
description: 'The ordering of items from the point of view of the blockchain,
not the page listing itself. By default, we return oldest first, newest last.
'
responses:
'200':
description: Return the address content
content:
application/json:
schema:
$ref: '#/components/schemas/address_txs_content'
'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'
/addresses/{address}/transactions:
get:
tags:
- Cardano » Addresses
summary: Address transactions
description: Transactions on the address.
parameters:
- in: path
name: address
required: true
schema:
type: string
description: Bech32 address.
example: addr1qxqs59lphg8g6qndelq8xwqn60ag3aeyfcp33c2kdp46a09re5df3pzwwmyq946axfcejy5n4x0y99wqpgtp2gd0k09qsgy6pz
- in: query
name: count
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 100
description: The number of transactions per page.
- in: query
name: page
required: false
schema:
type: integer
minimum: 1
maximum: 21474836
default: 1
description: The page number for listing the results.
- in: query
name: order
required: false
schema:
type: string
enum:
- asc
- desc
default: asc
description: 'The ordering of items from the point of view of the blockchain,
not the page listing itself. By default, we return oldest first, newest last.
'
- in: query
name: from
required: false
schema:
type: string
description: 'The block number and optionally also index from which (inclusive) to start search for results, concatenated using colon.
Has to be lower than or equal to `to` parameter.
'
example: '8929261'
- in: query
name: to
required: false
schema:
type: string
description: 'The block number and optionally also index where (inclusive) to end the search for results, concatenated using colon.
Has to be higher than or equal to `from` parameter.
'
example: '9999269:10'
responses:
'200':
description: Return the address content
content:
application/json:
schema:
$ref: '#/components/schemas/address_transactions_content'
'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'
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
'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:
address_utxo_content:
type: array
items:
type: object
properties:
address:
type: string
description: Bech32 encoded addresses - useful when querying by payment_cred
example: addr1qxqs59lphg8g6qndelq8xwqn60ag3aeyfcp33c2kdp46a09re5df3pzwwmyq946axfcejy5n4x0y99wqpgtp2gd0k09qsgy6pz
tx_hash:
type: string
description: Transaction hash of the UTXO
tx_index:
type: integer
deprecated: true
description: UTXO index in the transaction
output_index:
type: integer
description: UTXO index in the transaction
amount:
type: array
items:
type: object
description: The sum of all the UTXO per asset
properties:
unit:
type: string
format: Lovelace or concatenation of asset policy_id and hex-encoded asset_name
description: The unit of the value
quantity:
type: string
description: The quantity of the unit
required:
- unit
- quantity
block:
type: string
description: Block hash of the UTXO
data_hash:
type: string
nullable: true
description: The hash of the transaction output datum
inline_datum:
type: string
nullable: true
description: CBOR encoded inline datum
example: 19a6aa
reference_script_hash:
type: string
nullable: true
description: The hash of the reference script of the output
example: 13a3efd825703a352a8f71f4e2758d08c28c564e8dfcce9f77776ad1
required:
- address
- tx_hash
- tx_index
- output_index
- amount
- block
- data_hash
- inline_datum
- reference_script_hash
example:
- address: addr1qxqs59lphg8g6qndelq8xwqn60ag3aeyfcp33c2kdp46a09re5df3pzwwmyq946axfcejy5n4x0y99wqpgtp2gd0k09qsgy6pz
tx_hash: 39a7a284c2a0948189dc45dec670211cd4d72f7b66c5726c08d9b3df11e44d58
output_index: 0
amount:
- unit: lovelace
quantity: '42000000'
block: 7eb8e27d18686c7db9a18f8bbcfe34e3fed6e047afaa2d969904d15e934847e6
data_hash: 9e478573ab81ea7a8e31891ce0648b81229f408d596a3483e6f4f9b92d3cf710
inline_datum: null
reference_script_hash: null
- address: addr1qxqs59lphg8g6qndelq8xwqn60ag3aeyfcp33c2kdp46a09re5df3pzwwmyq946axfcejy5n4x0y99wqpgtp2gd0k09qsgy6pz
tx_hash: 4c4e67bafa15e742c13c592b65c8f74c769cd7d9af04c848099672d1ba391b49
output_index: 0
amount:
- unit: lovelace
quantity: '729235000'
block: 953f1b80eb7c11a7ffcd67cbd4fde66e824a451aca5a4065725e5174b81685b7
data_hash: null
inline_datum: null
reference_script_hash: null
- address: addr1qxqs59lphg8g6qndelq8xwqn60ag3aeyfcp33c2kdp46a09re5df3pzwwmyq946axfcejy5n4x0y99wqpgtp2gd0k09qsgy6pz
tx_hash: 768c63e27a1c816a83dc7b07e78af673b2400de8849ea7e7b734ae1333d100d2
output_index: 1
amount:
- unit: lovelace
quantity: '42000000'
- unit: b0d07d45fe9514f80213f4020e5a61241458be626841cde717cb38a76e7574636f696e
quantity: '12'
block: 5c571f83fe6c784d3fbc223792627ccf0eea96773100f9aedecf8b1eda4544d7
data_hash: null
inline_datum: null
reference_script_hash: null
address_content_total:
type: object
properties:
address:
type: string
description: Bech32 encoded address
example: addr1qxqs59lphg8g6qndelq8xwqn60ag3aeyfcp33c2kdp46a09re5df3pzwwmyq946axfcejy5n4x0y99wqpgtp2gd0k09qsgy6pz
received_sum:
type: array
items:
type: object
description: The sum of all the UTXO per asset
properties:
unit:
type: string
format: Lovelace or concatenation of asset policy_id and hex-encoded asset_name
description: The unit of the value
quantity:
type: string
description: The quantity of the unit
required:
- unit
- quantity
example:
- unit: lovelace
quantity: '42000000'
- unit: b0d07d45fe9514f80213f4020e5a61241458be626841cde717cb38a76e7574636f696e
quantity: '12'
sent_sum:
type: array
items:
type: object
description: The sum of all the UTXO per asset
properties:
unit:
type: string
format: Lovelace or concatenation of asset policy_id and hex-encoded asset_name
description: The unit of the value
quantity:
type: string
description: The quantity of the unit
required:
- unit
- quantity
example:
- unit: lovelace
quantity: '42000000'
- unit: b0d07d45fe9514f80213f4020e5a61241458be626841cde717cb38a76e7574636f696e
quantity: '12'
tx_count:
type: integer
example: 12
description: Count of all transactions on the address
required:
- address
- received_sum
- sent_sum
- tx_count
address_content:
type: object
properties:
address:
type: string
description: Bech32 encoded addresses
example: addr1qxqs59lphg8g6qndelq8xwqn60ag3aeyfcp33c2kdp46a09re5df3pzwwmyq946axfcejy5n4x0y99wqpgtp2gd0k09qsgy6pz
amount:
type: array
items:
type: object
description: The sum of all the UTXO per asset
properties:
unit:
type: string
format: Lovelace or concatenation of asset policy_id and hex-encoded asset_name
description: The unit of the value
quantity:
type: string
description: The quantity of the unit
required:
- unit
- quantity
example:
- unit: lovelace
quantity: '42000000'
- unit: b0d07d45fe9514f80213f4020e5a61241458be626841cde717cb38a76e7574636f696e
quantity: '12'
stake_address:
type: string
nullable: true
example: stake1ux3g2c9dx2nhhehyrezyxpkstartcqmu9hk63qgfkccw5rqttygt7
description: Stake address that controls the key
type:
type: string
enum:
- byron
- shelley
example: shelley
description: Address era
script:
type: boolean
example: false
description: True if this is a script address
required:
- address
- amount
- stake_address
- type
- script
address_transactions_content:
type: array
items:
type: object
properties:
tx_hash:
type: string
description: Hash of the transaction
tx_index:
type: integer
description: Transaction index within the block
block_height:
type: integer
description: Block height
block_time:
type: integer
description: Block creation time in UNIX time
required:
- tx_hash
- tx_index
- block_height
- block_time
example:
- tx_hash: 8788591983aa73981fc92d6cddbbe643959f5a784e84b8bee0db15823f575a5b
tx_index: 6
block_height: 69
block_time: 1635505891
- tx_hash: 52e748c4dec58b687b90b0b40d383b9fe1f24c1a833b7395cdf07dd67859f46f
tx_index: 9
block_height: 4547
block_time: 1635505987
- tx_hash: e8073fd5318ff43eca18a852527166aa8008bee9ee9e891f585612b7e4ba700b
tx_index: 0
block_height: 564654
block_time: 1834505492
address_content_extended:
type: object
properties:
address:
type: string
description: Bech32 encoded addresses
example: addr1qxqs59lphg8g6qndelq8xwqn60ag3aeyfcp33c2kdp46a09re5df3pzwwmyq946axfcejy5n4x0y99wqpgtp2gd0k09qsgy6pz
amount:
type: array
items:
type: object
description: The sum of all the UTXO per asset
properties:
unit:
type: string
format: Lovelace or concatenation of asset policy_id and hex-encoded asset_name
description: The unit of the value
quantity:
type: string
description: The quantity of the unit
decimals:
type: integer
nullable: true
description: Number of decimal places of the asset unit. Primary data source is CIP68 reference NFT with a fallback to off-chain metadata.
has_nft_onchain_metadata:
type: boolean
description: True if the latest minting transaction includes metadata (best-effort)
required:
- unit
- quantity
- decimals
- has_nft_onchain_metadata
example:
- unit: lovelace
quantity: '42000000'
decimals: 6
has_nft_onchain_metadata: false
- unit: b0d07d45fe9514f80213f4020e5a61241458be626841cde717cb38a76e7574636f696e
quantity: '12'
decimals: null
has_nft_onchain_metadata: true
stake_address:
type: string
nullable: true
example: stake1ux3g2c9dx2nhhehyrezyxpkstartcqmu9hk63qgfkccw5rqttygt7
description: Stake address that controls the key
type:
type: string
enum:
- byron
- shelley
example: shelley
description: Address era
script:
type: boolean
example: false
description: True if this is a script address
required:
- address
- amount
- stake_address
- type
- script
address_txs_content:
type: array
items:
type: string
description: Hash of the transaction
example:
- 2dd15e0ef6e6a17841cb9541c27724072ce4d4b79b91e58432fbaa32d9572531
- 1a0570af966fb355a7160e4f82d5a80b8681b7955f5d44bec0dde628516157f0
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.
'