# NACHO API — Cardano Blockchain Data Service
> A Cardano API-as-a-Service providing real-time blockchain data via REST, GraphQL, and WebSocket.
> Base URL: https://api.nacho.builders
> Sign up for a free API key: https://app.nacho.builders
> Full docs: https://app.nacho.builders/docs
> AI Agent setup guide: https://app.nacho.builders/docs/sdks/ai-agents
> Machine-readable OpenAPI spec: https://app.nacho.builders/openapi.yaml

## Authentication
All endpoints require an API key in the request header: apikey: napi_xxxx
Sign up for a free account at https://app.nacho.builders — a free API key is created automatically.
The free tier covers standard REST and explorer endpoints within rate limits.
GraphQL queries, Ogmios WebSocket, and transaction submission consume credits and may require a paid plan for higher volume.

## Networks
Pass {network} as either: mainnet (production) or preprod (testnet/testing)

## Standard REST Endpoints (free tier)

### GET /api/public/pool-info?poolId={poolId}
Cardano stake pool information: ticker, name, margin (0-1 decimal), fixedCost (lovelace string),
pledge (lovelace string), activeStake (lovelace string), delegatorCount, blocksLifetime, blocksEpoch.
poolId: bech32 format — pool1... (mainnet) or pool_test1... (preprod)

### GET /api/public/pool-status
NACHO pool live statistics: activeStake (ADA integer), delegators, blocksMinted,
lifetimeBlocks, margin, pledge, relay health, current network tip.

### GET /api/public/stake-account?address={stakeAddress}
Stake account info: registered (bool), delegatedPoolId, rewardsBalance (lovelace string),
totalStake (lovelace string).
stakeAddress: stake1... (mainnet) or stake_test1... (preprod)

### GET /api/public/tx-status?txHash={txHash}
Transaction confirmation: found (bool), blockNo, blockTime (ISO8601), confirmations, fee (lovelace string).
txHash: 64 hex characters. Poll this after submitting a transaction.

### GET /api/public/price
Current ADA/USD rate: { ada_usd: float, updated_at: ISO8601 }. Cached 60 seconds.

### GET /api/public/protocol-parameters
Current Cardano network protocol parameters (Ogmios format). Cached 1 hour.

## Explorer Endpoints (free tier)

### GET /v2/explorer/{network}/stats
Network overview: blockHeight, slotNo, epochNo, epochProgress (0-100), totalTransactions,
circulatingSupply (lovelace string), maxSupply, treasury, reserves, activeStake,
activePools, activeDelegators.

### GET /v2/explorer/{network}/blocks?page=1&limit=25
Recent blocks (paginated): blockNo, hash, slotNo, time (ISO8601), txCount, size,
poolId, poolTicker, totalFees (lovelace string), totalOutput (lovelace string).
Response includes: data[], total, page, pageSize, hasMore.

### GET /v2/explorer/{network}/block/{id}
Block by number or hash: blockNo, hash, slotNo, epochNo, epochSlotNo, time, txCount,
size, poolId, poolTicker, poolName, totalOutput (lovelace), totalFees (lovelace).

### GET /v2/explorer/{network}/tx/{hash}
Full transaction: hash, blockNo, blockHash, epochNo, blockTime, slotNo, fee, totalOutput,
deposit, size, validContract, scriptSize, invalidBefore, invalidHereafter,
inputs[], outputs[], certificates[], withdrawals[], metadata[], redeemers[], mints[], collateral[].
All ADA amounts as lovelace strings. Tokens: policyId, assetName, quantity (lovelace string).

### GET /v2/explorer/{network}/address/{address}
Address info: type (base/enterprise/reward/script/byron), stakeAddress, balance (lovelace),
tokenCount, utxoCount, firstSeen (ISO8601), lastSeen (ISO8601).

### GET /v2/explorer/{network}/address/{address}/utxos?page=1&limit=25
Address UTxOs (paginated): txHash, outputIndex, value (lovelace string), tokens[],
blockNo, blockTime (ISO8601), datumHash.

### GET /v2/explorer/{network}/pool/{poolId}
Full pool info: poolId (hex), poolIdBech32, ticker, name, liveStake, activeStake,
saturation (0-1), delegatorCount, pledge, pledgeMet, margin (0-1), fixedCost,
lifetimeBlocks, epochBlocks, lifetimeRewards, ros30d (30-day return on stake),
rewardAddress, owners[], relays[], registeredEpoch, retiring (epoch number, if applicable).

### GET /v2/explorer/{network}/dreps?page=1&pageSize=25&activeOnly=false
Governance DReps (paginated): drepIdBech32, type (registered/abstain/noConfidence),
name, givenName, isActive, votingPower (lovelace string), delegatorCount, votesCount.

## Advanced Endpoints

### POST /v1/graphql
GraphQL queries over the full Cardano DB-Sync schema (via Hasura).
Content-Type: application/json
Body: { "query": "...", "variables": {} }
Returns raw GraphQL response. Available on all tiers. Rate: 100 req/s (free), 500 req/s (paid).

### POST /v1/submit
Submit signed Cardano transaction.
Content-Type: application/cbor
Body: raw CBOR bytes of signed transaction
Returns: { "txId": "...", "status": "submitted" }
Use GET /api/public/tx-status to poll for confirmation.
Free tier: 10 tx/hour. Paid tier: unlimited.

### WebSocket: wss://api.nacho.builders/v1/ogmios (mainnet)
### WebSocket: wss://api.nacho.builders/v1/preprod/ogmios (preprod)
Ogmios 6.x JSON-RPC. Methods: queryNetwork/tip, queryLedgerState/utxo,
queryLedgerState/protocolParameters, submitTransaction, and all standard Ogmios methods.
Pass apikey in WebSocket handshake headers.

## Response Conventions
- ADA amounts: lovelace strings (1 ADA = 1,000,000 lovelace). Convert: divide by 1,000,000.
- Dates: ISO8601 strings (e.g. "2024-01-15T10:30:00.000Z")
- Hashes: lowercase hex strings
- Pool IDs: bech32 (pool1...) in public endpoints; both bech32 and hex in explorer endpoints
- Pagination: page (1-indexed), limit or pageSize (max 100)
- Large integers serialized as strings to avoid JavaScript precision loss

## Error Responses
{ "error": "string", "message": "string" }
HTTP 400: bad input | 401: missing/invalid API key | 404: not found | 429: rate limited | 500: server error

## Quick Start for AI Agents
To configure this API as a tool in your AI agent:
- Claude Code (MCP): npx -y nacho-api-mcp — see https://app.nacho.builders/docs/sdks/ai-agents-claude
- ChatGPT (Actions): import https://app.nacho.builders/openapi.yaml — see https://app.nacho.builders/docs/sdks/ai-agents-chatgpt
- Python/LangChain: pip install nacho-api-langchain — see https://app.nacho.builders/docs/sdks/ai-agents-opensource