canonical: https://jentic.com/apis/blockfrost.io/blockfrost

# Blockfrost.io ~ API Documentation

Jentic publishes the only available OpenAPI specification for Blockfrost.io, keeping it validated and agent-ready. Blockfrost is a hosted Cardano backend that exposes accounts, addresses, native assets, blocks, epochs, governance records, mempool state, pool data, scripts, transactions, and metadata across mainnet, preprod, and preview networks. It also includes IPFS pinning endpoints for storing off-chain content alongside Cardano transactions. Authentication uses a per-project header token, and a single project is scoped to one network.

## For AI agents

Query the Cardano blockchain - accounts, addresses, assets, blocks, transactions, governance, and pools - and pin files to IPFS through one hosted API.

## Scope

Does not build, sign, or custody Cardano transactions, and does not run smart contracts on-chain - use for reading Cardano state, submitting pre-signed transactions, and IPFS pinning only.

## Capabilities

- Resolve a Cardano stake or payment address to its balance, UTxOs, and reward history
- Look up native asset metadata, supply, and on-chain transaction history by policy ID
- Retrieve block, epoch, and slot data including transaction lists and protocol parameters
- Query Cardano governance state including DReps, proposals, votes, and committee members
- Submit and inspect transactions, including raw CBOR retrieval for offline analysis
- List active stake pools, their saturation, pledge, and historical performance
- Pin and retrieve files on IPFS via the integrated gateway with Cardano-linked metadata

## Use cases

### Cardano wallet portfolio dashboard

Build a portfolio dashboard that resolves Cardano stake and payment addresses into balances, UTxO sets, asset holdings, and reward history. Blockfrost exposes /accounts/{stake_address}, /addresses/{address}, and /addresses/{address}/utxos, returning both ADA balances in Lovelaces and any native assets held. Pagination defaults to 100 items with a page query parameter, and results are sorted ascending unless ?order=desc is passed.

Example prompt: Call GET /accounts/{stake_address} for a given stake address and return the controlled_amount in ADA along with the rewards_sum.

### Native asset and NFT lookup

Resolve Cardano native assets and NFTs by policy ID or asset fingerprint. The /assets, /assets/{asset}, /assets/policy/{policy_id}, and /assets/{asset}/transactions endpoints return supply, metadata, mint history, and ownership transfers. This supports NFT marketplace listings, collection explorers, and royalty tracking workflows.

Example prompt: Call GET /assets/policy/{policy_id} for a Cardano NFT collection policy ID and return the list of asset names with their initial mint transaction hashes.

### Governance and DRep tracking

Track Cardano on-chain governance under the Conway era. Blockfrost exposes /governance/dreps, /governance/dreps/{drep_id}/votes, and /governance/proposals to enumerate delegated representatives, their voting records, and active governance proposals with parameters and withdrawals. Useful for governance dashboards, DRep discovery tools, and on-chain political analytics.

Example prompt: Call GET /governance/dreps and return the top 10 DReps ordered by voting power, including their drep_id and amount.

### Stake pool analytics

Power stake pool analytics with /pools, /pools/{pool_id}, /pools/{pool_id}/history, and /pools/{pool_id}/delegators. The endpoints return pledge, saturation, declared margin, fixed cost, and per-epoch rewards. Combine with /epochs/{number}/parameters to compute effective ROA per epoch and surface staking recommendations.

Example prompt: Call GET /pools/{pool_id}/history?count=10 and return the per-epoch rewards and active stake values for the last ten epochs.

### AI agent Cardano research assistant

Let an AI agent answer Cardano questions by searching Jentic for the right Blockfrost operation, loading its schema, and executing the call with the project_id token held in your Jentic One instance. The agent never reads the Blockfrost docs site or handles the raw API key - it discovers operations by intent and executes against mainnet, preprod, or preview based on which token is loaded.

Example prompt: Search Jentic for 'look up a Cardano address balance', load the schema for the matching Blockfrost operation, and execute it for stake address stake1u9...

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /accounts/{stake_address} | Get balance and reward history for a stake address |
| GET | /addresses/{address} | Resolve a payment address to its current state |
| GET | /assets/{asset} | Look up a native asset by fingerprint |
| GET | /blocks/latest | Return the most recent block on the chain |
| GET | /governance/dreps | List Cardano DReps and their voting power |
| GET | /pools/{pool_id} | Get a stake pool's parameters and current state |
| GET | /epochs/latest/parameters | Return the current epoch's protocol parameters |
| GET | /genesis | Return Cardano network genesis parameters |

## Key resources

- **Accounts** — Stake address state including balances, rewards, delegation history, and registered MIRs
- **Addresses** — Payment address details, UTxOs, transactions, and associated assets
- **Assets** — Native token and NFT metadata, supply, history, and policy-level enumeration
- **Blocks** — Block lookup by hash, height, slot, or epoch with embedded transactions and addresses touched
- **Epochs** — Per-epoch summaries including stake distribution, rewards, and protocol parameters
- **Governance** — DReps, proposals, committee members, and votes from the Conway era
- **Pools** — Stake pool registry, history, delegators, retirement status, and metadata
- **Transactions** — Submit transactions and look up inputs, outputs, certificates, and metadata
- **IPFS** — Pin files, query pin state, and serve content through the Blockfrost gateway

## Why Jentic

- **Setup:** Wiring Blockfrost by hand means sending its project_id header, and picking the right network host among Cardano mainnet, preprod, and preview. Through Jentic you install once, import Blockfrost from the API Directory, store the project_id token once, and your agent calls it.
- **Permission scoping:** Blockfrost puts the resource id in the URL path (/accounts/{stake_address}, /pools/{pool_id}) and the Cardano reads are non-mutating, so scope the agent to the lookups it needs, such as reading an account, an address, or a stake pool. You choose that set, so any transaction-submit or IPFS-pin operation is not included unless you add it.
- **Credential handling:** Your Blockfrost project_id token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'look up a Cardano stake pool' or 'read the latest block', and Jentic returns the matching Blockfrost operation with its input schema so the agent calls the right endpoint without browsing the docs.

## Related APIs

- **Blockchain Data API** — Blockchain.com provides equivalent on-chain data access for the Bitcoin network instead of Cardano
- **Blockfrost** — Self-reference for Cardano data access
- **Blynk** — IoT device platform - pair when triggering hardware from Cardano on-chain events

## FAQ

### Why is there no official OpenAPI spec for Blockfrost.io?

Blockfrost does publish endpoint documentation, but Jentic generates and maintains the structured OpenAPI specification used here so that AI agents and developers can call Blockfrost.io via consistent tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Blockfrost API use?

Blockfrost requires a project_id token sent in the project_id HTTP header. Each token is scoped to a single network - mainnet, preprod, preview, or IPFS - so switching networks means switching tokens. Through Jentic, the token is held in the encrypted vault and injected at execution; the agent never sees the raw value.

### Can I submit Cardano transactions through this API?

Yes. POST /tx/submit accepts a CBOR-serialised signed transaction and returns the transaction hash if accepted by the network. You build and sign the transaction client-side (typically with cardano-serialization-lib or a wallet), then send the bytes to Blockfrost for relay to the node.

### What are the rate limits for the Blockfrost API?

Blockfrost limits each IP to 10 requests per second with a burst of 500 requests, cooling off at 10 requests per second. On top of that, daily request quotas apply per project based on your Blockfrost plan. Exceeding the daily quota returns HTTP 402, and sustained flooding triggers HTTP 418 auto-bans.

### How do I look up Cardano native assets through Jentic?

Search Jentic for 'look up a Cardano native asset by policy ID', load the schema for /assets/policy/{policy_id}, and execute it. The returned list contains asset fingerprints you can pass to /assets/{asset} for full metadata. Install the SDK with pip install jentic and call await client.execute(ExecutionRequest(...)).

### Does Blockfrost cover Cardano governance and DReps?

Yes. The /governance/dreps, /governance/dreps/{drep_id}/votes, and /governance/proposals endpoints return Conway-era governance state including delegated representatives, voting records, proposals, and parameter change requests. Use these to build governance dashboards or DRep discovery tools.

### Can I pin files to IPFS with Blockfrost?

Yes. The IPFS endpoints (/ipfs/add, /ipfs/pin/add/{IPFS_path}, /ipfs/pin/list) let you upload up to 100MB per file, pin content, and query pin status. Note that pinning requires an IPFS-network project_id, not a Cardano network token.

### Can I limit what my agent is allowed to do with the Blockfrost API?

Yes. Because you run Jentic One yourself, your own rules decide which Blockfrost operations and credentials the agent may use, so you can allow only the read lookups it needs, such as GET /accounts/{stake_address}, GET /addresses/{address}, or GET /pools/{pool_id}. Blockfrost puts the resource id in the URL path and these Cardano reads are non-mutating, so the agent can query state without changing anything. Mutating operations like the transaction submit at POST /tx/submit or the IPFS pinning endpoints are not included unless you add them to the allowed set. The project_id token stays with your instance and is injected only for the calls you have permitted.