{ "openapi": "3.0.2", "info": { "title": "node.kadia.io — public Ergo node API", "version": "6.0.2", "description": "The routes the public gateway at https://node.kadia.io serves, taken from the Rust Ergo node's own OpenAPI document. Everything else on the node answers 403 at the gateway. No API key; CORS open; request bodies capped at 1 MB.", "license": { "name": "CC0 1.0 Universal", "url": "https://raw.githubusercontent.com/ergoplatform/ergo/master/LICENSE" } }, "servers": [ { "url": "https://node.kadia.io" } ], "components": { "schemas": { "ADDigest": { "description": "Base16-encoded 33 byte digest - digest with extra byte with tree height", "type": "string", "format": "base16", "example": "333ab9da11fc216660e974842cc3b7705e62ebb9e0bf5ff78e53f9cd40abadd117" }, "ApiError": { "description": "Error response from API", "type": "object", "required": [ "error", "reason", "detail" ], "properties": { "error": { "type": "integer", "description": "Error code", "example": 500 }, "reason": { "type": "string", "description": "Error message explaining the reason of the error", "example": "Internal server error" }, "detail": { "type": "string", "nullable": true, "description": "Detailed error description" } } }, "Asset": { "description": "Token detail in the transaction", "type": "object", "required": [ "tokenId", "amount" ], "properties": { "tokenId": { "$ref": "#/components/schemas/Digest32" }, "amount": { "description": "Amount of the token", "type": "integer", "format": "int64", "example": 1000 } } }, "BalanceInfo": { "type": "object", "description": "Balance information", "required": [ "nanoErgs", "tokens" ], "properties": { "nanoErgs": { "type": "integer", "format": "int64", "description": "Balance of nanoERGs" }, "tokens": { "type": "array", "description": "Balance of tokens", "items": { "type": "object", "properties": { "tokenId": { "$ref": "#/components/schemas/ModifierId", "description": "Identifier of the token" }, "amount": { "type": "integer", "format": "int64", "description": "Amount of the token" }, "decimals": { "type": "integer", "description": "Number of decimals of the token" }, "name": { "type": "string", "description": "Name of the token, if any" } } } } } }, "BlockADProofs": { "type": "object", "required": [ "headerId", "proofBytes", "digest", "size" ], "properties": { "headerId": { "description": "Identifier of a header of the block which contains the proofs", "$ref": "#/components/schemas/ModifierId" }, "proofBytes": { "description": "Serialized bytes of the authenticated dictionary proof", "$ref": "#/components/schemas/SerializedAdProof" }, "digest": { "description": "Hash of the proofBytes", "$ref": "#/components/schemas/Digest32" }, "size": { "description": "Size in bytes", "type": "integer", "format": "int32" } } }, "BlockHeader": { "description": "Header of a block. It authenticates link to a previous block, other block sections (transactions, UTXO set transformation proofs, extension), UTXO set, votes for blockchain parameters to be changed and proof-of-work related data.", "type": "object", "required": [ "id", "timestamp", "version", "adProofsRoot", "stateRoot", "transactionsRoot", "nBits", "extensionHash", "powSolutions", "height", "difficulty", "parentId", "votes" ], "properties": { "id": { "description": "Block id", "$ref": "#/components/schemas/ModifierId" }, "timestamp": { "description": "Block generation time reported by a miner", "$ref": "#/components/schemas/Timestamp" }, "version": { "description": "Protocol version used to generate the block", "$ref": "#/components/schemas/Version" }, "adProofsRoot": { "description": "Digest of UTXO set transformation proofs", "$ref": "#/components/schemas/Digest32" }, "stateRoot": { "description": "AVL+ tree digest of UTXO set (after the block is applied)", "$ref": "#/components/schemas/ADDigest" }, "transactionsRoot": { "description": "Merkle tree digest of transactions in the block (BlockTransactions section)", "$ref": "#/components/schemas/Digest32" }, "nBits": { "description": "Proof-of-work target (difficulty encoded)", "type": "integer", "format": "int64", "minimum": 0, "example": 19857408 }, "extensionHash": { "description": "Merkle tree digest of the extension section of the block", "$ref": "#/components/schemas/Digest32" }, "powSolutions": { "description": "Solution for the proof-of-work puzzle", "$ref": "#/components/schemas/PowSolutions" }, "height": { "description": "Height of the block (genesis block height == 1)", "type": "integer", "format": "int32", "minimum": 0, "example": 667 }, "difficulty": { "type": "string", "example": "9575989248" }, "parentId": { "$ref": "#/components/schemas/ModifierId" }, "votes": { "description": "Votes for changing system parameters", "$ref": "#/components/schemas/Votes" }, "size": { "description": "Size of the header in bytes", "type": "integer", "format": "int32" }, "extensionId": { "description": "Hash of the extension section of the block == hash(modifier type id, header id, extensionHash)", "$ref": "#/components/schemas/ModifierId" }, "transactionsId": { "description": "Hash of the transactions section of the block == hash(modifier type id, header id, transactionsRoot)", "$ref": "#/components/schemas/ModifierId" }, "adProofsId": { "description": "Hash of the UTXO set transformation proofs section of the block == hash(modifier type id, header id, adProofsRoot)", "$ref": "#/components/schemas/ModifierId" } } }, "BlockTransactions": { "description": "Section of a block which contains transactions.", "type": "object", "required": [ "headerId", "transactions", "size" ], "properties": { "headerId": { "description": "Identifier of a header of a corresponding block", "$ref": "#/components/schemas/ModifierId" }, "transactions": { "description": "Transactions of the block", "$ref": "#/components/schemas/Transactions" }, "size": { "description": "Size in bytes of all block transactions", "type": "integer", "format": "int32" } } }, "Digest32": { "description": "Base16-encoded 32 byte digest", "type": "string", "format": "base16", "example": "4ab9da11fc216660e974842cc3b7705e62ebb9e0bf5ff78e53f9cd40abadd117" }, "ErgoAddress": { "description": "Encoded Ergo Address", "type": "string", "example": "3WwbzW6u8hKWBcL1W7kNVMr25s2UHfSBnYtwSHvrRQt7DdPuoXrt" }, "ErgoBoxWithSpendingProof": { "allOf": [ { "$ref": "#/components/schemas/ErgoTransactionOutput" }, { "type": "object", "description": "Box indexed with extra information", "required": [ "spendingProof", "boxId" ], "properties": { "spendingProof": { "$ref": "#/components/schemas/SpendingProof" }, "boxId": { "$ref": "#/components/schemas/TransactionBoxId" } } } ] }, "ErgoTransaction": { "type": "object", "description": "ErgoTransaction is an atomic operation which changes UTXO state.", "required": [ "inputs", "dataInputs", "outputs" ], "properties": { "id": { "description": "Id of the transaction", "$ref": "#/components/schemas/TransactionId" }, "inputs": { "description": "Inputs, that will be spent by this transaction", "type": "array", "items": { "$ref": "#/components/schemas/ErgoTransactionInput" } }, "dataInputs": { "description": "Read-only inputs, that are not going to be spent by transaction.", "type": "array", "items": { "$ref": "#/components/schemas/ErgoTransactionDataInput" } }, "outputs": { "description": "Outputs of the transaction, i.e. box candidates to be created by this transaction.", "type": "array", "items": { "$ref": "#/components/schemas/ErgoTransactionOutput" } }, "size": { "description": "Size of ErgoTransaction in bytes", "type": "integer", "format": "int32" } } }, "ErgoTransactionDataInput": { "type": "object", "required": [ "boxId" ], "properties": { "boxId": { "$ref": "#/components/schemas/TransactionBoxId" } } }, "ErgoTransactionInput": { "type": "object", "required": [ "boxId", "spendingProof" ], "properties": { "boxId": { "$ref": "#/components/schemas/TransactionBoxId" }, "spendingProof": { "$ref": "#/components/schemas/SpendingProof" } } }, "ErgoTransactionOutput": { "type": "object", "required": [ "value", "ergoTree", "additionalRegisters", "creationHeight" ], "properties": { "boxId": { "$ref": "#/components/schemas/TransactionBoxId" }, "value": { "description": "Amount of Ergo token", "type": "integer", "format": "int64", "minimum": 0, "example": 147 }, "ergoTree": { "$ref": "#/components/schemas/ErgoTree" }, "creationHeight": { "description": "Height the output was created at", "type": "integer", "format": "int32", "example": 9149 }, "assets": { "description": "Assets list in the transaction", "type": "array", "items": { "$ref": "#/components/schemas/Asset" } }, "additionalRegisters": { "$ref": "#/components/schemas/Registers" }, "transactionId": { "$ref": "#/components/schemas/TransactionId" }, "index": { "description": "Index in the transaction outputs", "type": "integer", "format": "int32" } } }, "ErgoTransactionWithInputBoxes": { "type": "object", "description": "Transaction indexed with extra information", "required": [ "id", "inputs", "dataInputs", "outputs", "size" ], "properties": { "id": { "$ref": "#/components/schemas/TransactionId" }, "inputs": { "description": "Transaction inputs", "type": "array", "items": { "$ref": "#/components/schemas/ErgoBoxWithSpendingProof" } }, "dataInputs": { "description": "Transaction data inputs", "type": "array", "items": { "$ref": "#/components/schemas/ErgoTransactionDataInput" } }, "outputs": { "description": "Transaction outputs", "type": "array", "items": { "$ref": "#/components/schemas/ErgoTransactionOutput" } }, "size": { "description": "Size in bytes", "type": "integer", "format": "int32" } } }, "ErgoTree": { "description": "Base16-encoded ergo tree bytes", "type": "string", "format": "base16", "example": "0008cd0336100ef59ced80ba5f89c4178ebd57b6c1dd0f3d135ee1db9f62fc634d637041" }, "Extension": { "description": "Section of a block which contains extension data.", "type": "object", "required": [ "headerId", "digest", "fields" ], "properties": { "headerId": { "description": "Identifier of a header of a corresponding block", "$ref": "#/components/schemas/ModifierId" }, "digest": { "description": "Root hash (aka digest) merkelized list of key-value records", "$ref": "#/components/schemas/Digest32" }, "fields": { "description": "List of key-value records", "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/KeyValueItem" } } } }, "FeeHistogram": { "description": "Fee histogram for transactions in mempool", "type": "array", "items": { "$ref": "#/components/schemas/FeeHistogramBin" } }, "FeeHistogramBin": { "description": "Fee histogram bin", "type": "object", "properties": { "nTxns": { "type": "integer", "format": "int32" }, "totalFee": { "type": "integer", "format": "int64" } } }, "FullBlock": { "description": "Block with header and transactions", "type": "object", "required": [ "header", "blockTransactions", "adProofs", "extension", "size" ], "properties": { "header": { "$ref": "#/components/schemas/BlockHeader" }, "blockTransactions": { "$ref": "#/components/schemas/BlockTransactions" }, "adProofs": { "$ref": "#/components/schemas/BlockADProofs" }, "extension": { "$ref": "#/components/schemas/Extension" }, "size": { "description": "Size in bytes", "type": "integer", "format": "int32" } } }, "HexString": { "description": "Base16-encoded bytes", "type": "string", "format": "base16", "example": "4ab9da11fc216660e974842cc3b7705e62ebb9e0bf5ff78e53f9cd40abadd117" }, "IndexedBlockTransactions": { "description": "Section of a block which contains indexed transactions.", "type": "object", "required": [ "headerId", "transactions", "size" ], "properties": { "headerId": { "description": "Identifier of a header of a corresponding block", "$ref": "#/components/schemas/ModifierId" }, "transactions": { "description": "IndexedTransactions of the block", "$ref": "#/components/schemas/IndexedTransactions" }, "size": { "description": "Size in bytes of all block transactions", "type": "integer", "format": "int32" } } }, "IndexedErgoBox": { "allOf": [ { "$ref": "#/components/schemas/ErgoTransactionOutput" }, { "type": "object", "description": "Box indexed with extra information", "required": [ "address", "spentTransactionId", "spendingHeight", "inclusionHeight", "globalIndex" ], "properties": { "address": { "$ref": "#/components/schemas/ErgoAddress" }, "spentTransactionId": { "description": "Transaction which spent the box", "nullable": true, "$ref": "#/components/schemas/ModifierId" }, "spendingHeight": { "description": "The height the box was spent at", "type": "integer", "format": "int32", "minimum": 0, "example": 147, "nullable": true }, "inclusionHeight": { "description": "The height the transaction containing the box was\nincluded in a block at. **P5 sentinel:** value `0` when\nthe box was returned from the mempool overlay (i.e.\n`includeUnconfirmed=true` and the box has not yet been\nincluded in a block). Confirmed boxes always have\n`inclusionHeight ≥ 1`, so `0` is the unique\ndiscriminator for overlay-sourced rows. Currently\nreachable via `/blockchain/box/unspent/byAddress` (POST\n+ GET); the remaining `unspent/by*` routes still hard-\nreject the overlay flags pre-cutover (see the API-level\n`description` for the up-to-date status).\n", "type": "integer", "format": "int32", "minimum": 0, "example": 147 }, "spendingProof": { "nullable": true, "$ref": "#/components/schemas/SpendingProof" }, "globalIndex": { "description": "Global index of the output in the blockchain. Assigned\nsequentially from `0` at first-indexed-output time\n(genesis output has `globalIndex = 0`), so this field\nalone does NOT discriminate mempool-overlay boxes from\nconfirmed ones — use `inclusionHeight = 0` for that\n(post-P5 only; see `inclusionHeight` description above).\n\n**`[inherited]` quirk:** the genesis output\n(`globalIndex = 0`) is observationally invisible to\nsegment-backed unspent queries\n(`/box/unspent/byAddress`,\n`/box/unspent/byTemplateHash`,\n`/box/unspent/byTokenId`, `/box/unspent/byErgoTree`)\non both Scala and Rust, because the underlying\nsegment filter excludes non-positive entries\n(`_ > 0`). It remains queryable via\n`/box/byId/{id}` and `/box/byIndex/0`.\n", "type": "integer", "format": "int64", "minimum": 0, "example": 83927 } } } ] }, "IndexedErgoTransaction": { "type": "object", "description": "Transaction indexed with extra information", "required": [ "id", "inputs", "dataInputs", "outputs", "inclusionHeight", "numConfirmations", "blockId", "timestamp", "index", "globalIndex", "size" ], "properties": { "id": { "$ref": "#/components/schemas/TransactionId" }, "inputs": { "description": "Transaction inputs", "type": "array", "items": { "$ref": "#/components/schemas/IndexedErgoBox" } }, "dataInputs": { "description": "Transaction data inputs", "type": "array", "items": { "$ref": "#/components/schemas/ErgoTransactionDataInput" } }, "outputs": { "description": "Transaction outputs", "type": "array", "items": { "$ref": "#/components/schemas/IndexedErgoBox" } }, "inclusionHeight": { "description": "Height of a block the transaction was included in", "type": "integer", "format": "int32", "example": 20998 }, "numConfirmations": { "description": "Number of transaction confirmations", "type": "integer", "format": "int32", "example": 20998 }, "blockId": { "description": "Id of the block the transaction was included in", "allOf": [ { "$ref": "#/components/schemas/ModifierId" } ] }, "timestamp": { "$ref": "#/components/schemas/Timestamp" }, "index": { "description": "index of the transaction in the block it was included in", "type": "integer", "format": "int32", "example": 3 }, "globalIndex": { "description": "Global index of the transaction in the blockchain", "type": "integer", "format": "int64", "example": 3565445 }, "size": { "description": "Size in bytes", "type": "integer", "format": "int32" } } }, "IndexedFullBlock": { "description": "Block with header and transactions", "type": "object", "required": [ "header", "blockTransactions", "adProofs", "extension", "size" ], "properties": { "header": { "$ref": "#/components/schemas/BlockHeader" }, "blockTransactions": { "$ref": "#/components/schemas/IndexedBlockTransactions" }, "adProofs": { "$ref": "#/components/schemas/BlockADProofs" }, "extension": { "$ref": "#/components/schemas/Extension" }, "size": { "description": "Size in bytes", "type": "integer", "format": "int32" } } }, "IndexedToken": { "type": "object", "description": "Token indexed with extra information", "required": [ "id", "boxId", "emissionAmount", "name", "description", "decimals" ], "properties": { "id": { "description": "Id of the token", "$ref": "#/components/schemas/ModifierId" }, "boxId": { "description": "Id of the box that created the token", "$ref": "#/components/schemas/ModifierId" }, "emissionAmount": { "description": "The total supply of the token", "type": "integer", "format": "int64", "minimum": 1, "example": 3500000 }, "name": { "description": "The name of the token", "type": "string" }, "description": { "description": "The description of the token", "type": "string" }, "decimals": { "description": "The number of decimals the token supports", "type": "integer", "format": "int32", "minimum": 0, "example": 8 } } }, "IndexedTransactions": { "description": "List of IndexedErgoTransaction objects", "type": "array", "items": { "$ref": "#/components/schemas/IndexedErgoTransaction" } }, "KeyValueItem": { "description": "Key-value record represented as a pair of hex strings in an array.", "type": "array", "items": { "$ref": "#/components/schemas/HexString" } }, "MerkleProof": { "type": "object", "description": "Merkle proof for a leaf, which is an array of bytes (e.g. a transaction identifier)", "required": [ "leafData", "levels" ], "properties": { "leafData": { "type": "string", "description": "Base16-encoded Merkle tree leaf bytes (the value pre-prefix-hash; verifier computes leaf hash as Blake2b256(0x00 || leafData))", "example": "cd665e49c834b0c25574fcb19a158d836f3f2aad8e91ac195f972534c25449b3" }, "levels": { "type": "array", "items": { "type": "array", "description": "pairs of hash and side of hash", "example": [ "018b7ae20a4acd23e3f1bf38671ce97103ad96d8f1c780b5e5e865e4873ae16337", 0 ], "items": { "anyOf": [ { "description": "hash", "type": "string" }, { "description": "side of hash", "type": "integer" } ] } }, "example": [ [ "018b7ae20a4acd23e3f1bf38671ce97103ad96d8f1c780b5e5e865e4873ae16337", 0 ] ] } } }, "ModifierId": { "description": "Base16-encoded 32 byte modifier id", "type": "string", "format": "base16", "example": "3ab9da11fc216660e974842cc3b7705e62ebb9e0bf5ff78e53f9cd40abadd117" }, "NodeInfo": { "description": "Data container for /info API request output. Contains information about node's state and configuration. Contains data about best block, best header, state, etc. Best block is the block with the maximum height.", "type": "object", "required": [ "name", "appVersion", "fullHeight", "headersHeight", "maxPeerHeight", "bestFullHeaderId", "previousFullHeaderId", "bestHeaderId", "headersScore", "fullBlocksScore", "stateRoot", "stateType", "stateVersion", "isMining", "peersCount", "unconfirmedCount", "difficulty", "currentTime", "launchTime", "genesisBlockId", "parameters" ], "properties": { "name": { "description": "Node's (peer) self-chosen name from config", "type": "string", "example": "my-node-1" }, "appVersion": { "description": "Node's application version", "type": "string", "example": "0.0.1" }, "fullHeight": { "type": "integer", "format": "int32", "description": "Height of the best block known to the node. Can be 'null' if state is empty (no full block is applied since node launch)", "minimum": 0, "example": 667, "nullable": true }, "headersHeight": { "type": "integer", "format": "int32", "description": "The height of the best header (i.e. the one with the maximum height). Can be 'null' if state is empty (no header applied since node launch)", "minimum": 0, "example": 667, "nullable": true }, "maxPeerHeight": { "type": "integer", "format": "int32", "description": "Maximum block height of connected peers. Can be 'null' if state is empty (no peer connected since node launch)", "minimum": 0, "example": 706162, "nullable": true }, "bestFullHeaderId": { "type": "string", "description": "Best full-block id (header id of such block). Can be 'null' if no full block is applied since node launch.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/ModifierId" } ] }, "previousFullHeaderId": { "type": "string", "description": "Header id of the parent block of the best full-block (i.e. previous block in the blockchain). Can be 'null' if no full block is applied since node launch", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/ModifierId" } ] }, "bestHeaderId": { "type": "string", "description": "Best header ID (hex representation). Can be 'null' if no header applied since node launch.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/ModifierId" } ] }, "stateRoot": { "type": "string", "nullable": true, "description": "Current UTXO set digest. Can be 'null' if state is empty (no full block is applied since node launch)", "example": "dab9da11fc216660e974842cc3b7705e62ebb9e0bf5ff78e53f9cd40abadd117" }, "stateType": { "description": "Whether the node is storing UTXO set or only its digest. Equals `digest` if only digest is stored, `utxo` if full UTXO set is stored.", "type": "string", "enum": [ "digest", "utxo" ] }, "stateVersion": { "description": "Id of a block where UTXO set digest is taken from. Can be 'null' if no full block is applied since node launch.", "type": "string", "example": "fab9da11fc216660e974842cc3b7705e62ebb9e0bf5ff78e53f9cd40abadd117", "nullable": true }, "isMining": { "description": "Whether the node is mining (i.e. generating blocks).", "type": "boolean", "example": true }, "peersCount": { "type": "integer", "description": "Number of peers this node is connected with.", "format": "int32", "minimum": 0, "example": 327 }, "unconfirmedCount": { "description": "Number of unconfirmed transactions in the mempool.", "type": "integer", "format": "int32", "minimum": 0, "maximum": 10000, "example": 327 }, "difficulty": { "type": "integer", "minimum": 0, "nullable": true, "example": 667, "description": "Difficulty on current bestFullHeaderId. Can be 'null' if no full block is applied since node launch. Difficulty is a BigInt integer." }, "currentTime": { "type": "integer", "description": "Current internal node time", "allOf": [ { "$ref": "#/components/schemas/Timestamp" } ] }, "launchTime": { "type": "integer", "description": "When the node was launched (in Java time format, UNIX time * 1000).", "allOf": [ { "$ref": "#/components/schemas/Timestamp" } ] }, "headersScore": { "type": "integer", "description": "Cumulative difficulty of best headers-chain. Can be 'null' if no headers is applied since node launch. headersScore is a BigInt integer.", "nullable": true }, "fullBlocksScore": { "type": "integer", "description": "Cumulative difficulty of best full blocks chain. Can be 'null' if no full block is applied since node launch. fullBlocksScore is a BigInt integer.", "nullable": true }, "genesisBlockId": { "type": "string", "description": "Header id of genesis block. Can be 'null' if genesis blocks is not produced yet.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/ModifierId" } ] }, "parameters": { "type": "object", "description": "System parameters which could be readjusted via collective miners decision.", "$ref": "#/components/schemas/Parameters" }, "eip27Supported": { "type": "boolean", "example": true, "description": "Whether EIP-27 locked in" }, "restApiUrl": { "type": "string", "example": "https://example.com", "description": "Publicly accessible url of node which exposes restApi in firewall" } } }, "Parameters": { "description": "System parameters which could be readjusted via collective miners decision.", "type": "object", "required": [ "height", "blockVersion", "storageFeeFactor", "minValuePerByte", "maxBlockSize", "maxBlockCost", "tokenAccessCost", "inputCost", "dataInputCost", "outputCost" ], "properties": { "height": { "type": "integer", "format": "int32", "description": "Height when current parameters were considered(not actual height). Can be '0' if state is empty", "minimum": 0, "example": 667, "nullable": false }, "storageFeeFactor": { "type": "integer", "format": "int32", "description": "Storage fee coefficient (per byte per storage period ~4 years)", "minimum": 0, "example": 100000, "nullable": false }, "minValuePerByte": { "type": "integer", "format": "int32", "description": "Minimum value per byte of an output", "minimum": 0, "example": 360, "nullable": false }, "maxBlockSize": { "type": "integer", "format": "int32", "description": "Maximum block size (in bytes)", "minimum": 0, "example": 1048576, "nullable": false }, "maxBlockCost": { "type": "integer", "format": "int32", "description": "Maximum cumulative computational cost of input scripts in block transactions", "minimum": 0, "example": 104876, "nullable": false }, "blockVersion": { "$ref": "#/components/schemas/Version", "nullable": false }, "tokenAccessCost": { "type": "integer", "format": "int32", "description": "Validation cost of a single token", "minimum": 0, "example": 100, "nullable": false }, "inputCost": { "type": "integer", "format": "int32", "description": "Validation cost per one transaction input", "minimum": 0, "example": 100, "nullable": false }, "dataInputCost": { "type": "integer", "format": "int32", "description": "Validation cost per one data input", "minimum": 0, "example": 100, "nullable": false }, "outputCost": { "type": "integer", "format": "int32", "description": "Validation cost per one transaction output", "minimum": 0, "example": 100, "nullable": false } } }, "PeersStatus": { "type": "object", "required": [ "lastIncomingMessage", "currentNetworkTime" ], "properties": { "lastIncomingMessage": { "type": "integer", "allOf": [ { "$ref": "#/components/schemas/Timestamp" } ] }, "currentNetworkTime": { "type": "integer", "allOf": [ { "$ref": "#/components/schemas/Timestamp" } ] } } }, "PowSolutions": { "description": "An object containing all components of pow solution", "type": "object", "required": [ "pk", "w", "n", "d" ], "properties": { "pk": { "type": "string", "description": "Base16-encoded public key", "example": "0350e25cee8562697d55275c96bb01b34228f9bd68fd9933f2a25ff195526864f5" }, "w": { "type": "string", "example": "0366ea253123dfdb8d6d9ca2cb9ea98629e8f34015b1e4ba942b1d88badfcc6a12" }, "n": { "type": "string", "example": "0000000000000000" }, "d": { "type": "number", "example": 987654321 } } }, "Registers": { "description": "Ergo box registers", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/SValue" }, "example": { "R4": "100204a00b08cd0336100ef59ced80ba5f89c4178ebd57b6c1dd0f3d135ee1db9f62fc634d637041ea02d192a39a8cc7a70173007301" } }, "SValue": { "description": "Base-16 encoded serialized Sigma-state value", "type": "string", "format": "base16", "example": "100204a00b08cd0336100ef59ced80ba5f89c4178ebd57b6c1dd0f3d135ee1db9f62fc634d637041ea02d192a39a8cc7a70173007301" }, "SerializedAdProof": { "description": "Base16-encoded ad proofs", "type": "string", "format": "base16", "example": "3ab9da11fc216660e974842cc3b7705e62ebb9e0bf5ff78e53f9cd40abadd1173ab9da11fc216660e974842cc3b7705e62ebb9e0bf5ff78e53f9cd40abadd1173ab9da11fc216660e974842cc3b7705e62ebb9e0bf5ff78e53f9cd40abadd117" }, "SerializedBox": { "type": "object", "required": [ "boxId", "bytes" ], "properties": { "boxId": { "$ref": "#/components/schemas/TransactionBoxId" }, "bytes": { "$ref": "#/components/schemas/HexString" } } }, "SnapshotsInfo": { "type": "object", "required": [ "availableManifests" ], "properties": { "availableManifests": { "description": "Map of available manifests, height -> hex manifest id. (The upstream Scala spec declares an array here, but its runtime encoder serves a JSON object keyed by height — this schema matches the served shape.)", "type": "object", "additionalProperties": { "type": "string" } } } }, "SpendingProof": { "description": "Spending proof for transaction input", "type": "object", "required": [ "proofBytes", "extension" ], "properties": { "proofBytes": { "$ref": "#/components/schemas/SpendingProofBytes" }, "extension": { "type": "object", "description": "Variables to be put into context", "additionalProperties": { "$ref": "#/components/schemas/SValue" }, "example": { "1": "a2aed72ff1b139f35d1ad2938cb44c9848a34d4dcfd6d8ab717ebde40a7304f2541cf628ffc8b5c496e6161eba3f169c6dd440704b1719e0" } } } }, "SpendingProofBytes": { "description": "Base16-encoded spending proofs", "type": "string", "format": "base16", "example": "4ab9da11fc216660e974842cc3b7705e62ebb9e0bf5ff78e53f9cd40abadd1173ab9da11fc216660e974842cc3b7705e62ebb9e0bf5ff78e53f9cd40abadd1173ab9da11fc216660e974842cc3b7705e62ebb9e0bf5ff78e53f9cd40abadd117" }, "Timestamp": { "description": "Basic timestamp definition", "type": "integer", "format": "int64", "example": 1524143059077 }, "TransactionBoxId": { "description": "Base16-encoded transaction box id bytes. Should be 32 bytes long", "type": "string", "format": "base16", "example": "1ab9da11fc216660e974842cc3b7705e62ebb9e0bf5ff78e53f9cd40abadd117" }, "TransactionId": { "description": "Base16-encoded transaction id bytes", "type": "string", "format": "base16", "example": "2ab9da11fc216660e974842cc3b7705e62ebb9e0bf5ff78e53f9cd40abadd117" }, "Transactions": { "description": "List of ErgoTransaction objects", "type": "array", "items": { "$ref": "#/components/schemas/ErgoTransaction" } }, "TransactionsWithInputBoxes": { "description": "List of ErgoTransaction augmented with input boxes", "type": "array", "items": { "$ref": "#/components/schemas/ErgoTransactionWithInputBoxes" } }, "Version": { "description": "Ergo blockchain protocol version", "type": "integer", "format": "int8", "example": 2 }, "Votes": { "description": "Base16-encoded votes for a soft-fork and parameters", "type": "string", "format": "base16", "example": "000000" } } }, "paths": { "/blocks": { "get": { "summary": "Get an array of header ids (hex encoded) for the given range of blockchain block heights. Returns a page of the whole list starting from `offset` and containing `limit` items.", "operationId": "getHeaderIds", "tags": [ "blocks" ], "parameters": [ { "in": "query", "name": "limit", "required": false, "description": "The number of items in list to return", "schema": { "type": "integer", "format": "int32", "minimum": 10, "maximum": 100, "default": 50 } }, { "in": "query", "name": "offset", "required": false, "description": "The first block height to include in the list", "schema": { "type": "integer", "format": "int32", "default": 0 } } ], "responses": { "200": { "description": "Array of header ids", "content": { "application/json": { "schema": { "type": "array", "description": "Array of header ids", "items": { "type": "string", "example": "8b7ae20a4acd23e3f1bf38671ce97103ad96d8f1c780b5e5e865e4873ae16337" }, "example": [ "8b7ae20a4acd23e3f1bf38671ce97103ad96d8f1c780b5e5e865e4873ae16337" ] } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/blocks/at/{blockHeight}": { "get": { "summary": "Get header ids at the given height", "operationId": "getFullBlockAt", "tags": [ "blocks" ], "parameters": [ { "in": "path", "name": "blockHeight", "required": true, "description": "Height of a block to retrieve header ids", "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "Array of header ids", "content": { "application/json": { "schema": { "type": "array", "description": "Array of header ids", "example": [ "8b7ae20a4acd23e3f1bf38671ce97103ad96d8f1c780b5e5e865e4873ae16337" ], "items": { "type": "string", "example": "8b7ae20a4acd23e3f1bf38671ce97103ad96d8f1c780b5e5e865e4873ae16337" } } } } }, "404": { "description": "Blocks at this height doesn't exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/blocks/chainSlice": { "get": { "summary": "Get headers in a specified range of heights", "operationId": "getChainSlice", "tags": [ "blocks" ], "parameters": [ { "in": "query", "name": "fromHeight", "required": false, "description": "Min header height (start of the range)", "schema": { "type": "integer", "format": "int32", "default": 0 } }, { "in": "query", "name": "toHeight", "required": false, "description": "Max header height of the range (last header height then omitted)", "schema": { "type": "integer", "format": "int32", "default": -1 } } ], "responses": { "200": { "description": "Array of headers", "content": { "application/json": { "schema": { "type": "array", "description": "Array of headers", "items": { "$ref": "#/components/schemas/BlockHeader" } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/blocks/{headerId}": { "get": { "summary": "Get the full block info by a given header id", "operationId": "getFullBlockById", "tags": [ "blocks" ], "parameters": [ { "in": "path", "name": "headerId", "required": true, "description": "ID of the header the wanted block", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Block object representing the full block data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FullBlock" } } } }, "404": { "description": "Block with this id doesn't exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/blocks/headerIds": { "post": { "summary": "Get full blocks by given header ids", "operationId": "getFullBlockByIds", "tags": [ "blocks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "responses": { "200": { "description": "Full blocks corresponding to ids provided", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FullBlock" } } } } }, "404": { "description": "No block exist for every id provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/blocks/{headerId}/header": { "get": { "summary": "Get the block header info by a given header id", "operationId": "getBlockHeaderById", "tags": [ "blocks" ], "parameters": [ { "in": "path", "name": "headerId", "required": true, "description": "ID of a wanted block header", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Block header object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlockHeader" } } } }, "404": { "description": "Block with this id doesn't exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/blocks/{headerId}/transactions": { "get": { "summary": "Get the block transactions info by a given signature", "operationId": "getBlockTransactionsById", "tags": [ "blocks" ], "parameters": [ { "in": "path", "name": "headerId", "required": true, "description": "ID of a wanted block transactions", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Block transaction object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlockTransactions" } } } }, "404": { "description": "Block with this id doesn't exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/blocks/{headerId}/proofFor/{txId}": { "get": { "summary": "Get Merkle proof for transaction", "operationId": "getProofForTx", "tags": [ "blocks" ], "parameters": [ { "in": "path", "name": "headerId", "required": true, "description": "ID of a wanted block transactions", "schema": { "type": "string" } }, { "in": "path", "name": "txId", "required": true, "description": "ID of a wanted transaction", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Merkle proof object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerkleProof" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/blocks/lastHeaders/{count}": { "get": { "summary": "Get the last headers objects", "operationId": "getLastHeaders", "tags": [ "blocks" ], "parameters": [ { "in": "path", "name": "count", "required": true, "description": "a number of block headers to return", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Array of block headers", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BlockHeader" } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/blocks/modifier/{modifierId}": { "get": { "summary": "Get the persistent modifier by its id", "operationId": "getModifierById", "tags": [ "blocks" ], "parameters": [ { "in": "path", "name": "modifierId", "required": true, "description": "ID of a wanted modifier", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Persistent modifier object" }, "404": { "description": "Modifier with this id doesn't exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/info": { "get": { "summary": "Get the information about the Node", "operationId": "getNodeInfo", "tags": [ "info" ], "responses": { "200": { "description": "Node info object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NodeInfo" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/transactions": { "post": { "summary": "Submit an Ergo transaction to unconfirmed pool to send it over the network", "operationId": "sendTransaction", "tags": [ "transactions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErgoTransaction" } } } }, "responses": { "200": { "description": "JSON with ID of the new transaction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionId" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/transactions/bytes": { "post": { "summary": "Submit an Ergo transaction given as hex-encoded transaction bytes to unconfirmed pool to send it over the network", "operationId": "sendTransactionAsBytes", "tags": [ "transactions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "string", "example": "02c9e71790399816b3e40b2207e9ade19a9b7fe0600186cfb8e2b115bfdb34b57f38cd3c9f2890d11720eb3bb993993f00ededf812a590d2993df094a7ca4f0213e4820e1ab831eed5dc5c72665396d3a01d2a12900f1c3ab77700b284ae24fa8e8f7754f86f2282c795db6b0b17df1c29cc0552e59d01f7d777c638a813333277271c2f8b4d99d01ff0e6ee8695697bdd5b568089395620d7198c6093ce8bc59b928611b1b12452c05addaa42f4beff6a0a6fe90000000380d0dbc3f40210090402040005c801040205c8010500040004000e2003faf2cb329f2e90d6d23b58d91bbb6c046aa143261cc21f52fbe2824bfcbf04d807d601e4c6a70408d602b2a5730000d603e4c6a70601d604e4c6a7080ed605e4c6a70505d606e4c6a70705d60795720399c1a7c1720299c17202c1a7eb027201d1ededededededededed93c27202c2a793e4c672020408720193e4c6720205059572039d9c72057eb272047301000573029d9c72057eb2720473030005730494e4c672020601720393e4c672020705720693e4c67202080e720493e4c67202090ec5a79572039072079c720672059272079c72067205917207730595ef720393b1db630872027306d801d608b2db63087202730700ed938c7208017308938c7208027206c8df35000508cd030c8f9c4dc08f3c006fa85a47c9156dedbede000a8b764c6e374fd097e873ba0405c8a8c105010105dc8b020e0266608cdea8baf0380008cd030c8f9c4dc08f3c006fa85a47c9156dedbede000a8b764c6e374fd097e873ba04c8df350000c0843d1005040004000e36100204a00b08cd0279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798ea02d192a39a8cc7a701730073011001020402d19683030193a38cc7b2a57300000193c2b2a57301007473027303830108cdeeac93b1a57304c8df350000" } } } }, "responses": { "200": { "description": "JSON with ID of the new transaction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionId" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/transactions/check": { "post": { "summary": "Checks an Ergo transaction without sending it over the network. Checks that transaction is valid and its inputs are in the UTXO set. Returns transaction identifier if the transaction is passing the checks.", "operationId": "checkTransaction", "tags": [ "transactions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErgoTransaction" } } } }, "responses": { "200": { "description": "JSON with ID of the new transaction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionId" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/transactions/checkBytes": { "post": { "summary": "Checks an Ergo transaction without sending it over the network given in form of hex-encoded transaction bytes. Checks that transaction is valid and its inputs are in the UTXO set. Returns transaction identifier if the transaction is passing the checks.", "operationId": "checkTransactionAsBytes", "tags": [ "transactions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "string", "example": "02c9e71790399816b3e40b2207e9ade19a9b7fe0600186cfb8e2b115bfdb34b57f38cd3c9f2890d11720eb3bb993993f00ededf812a590d2993df094a7ca4f0213e4820e1ab831eed5dc5c72665396d3a01d2a12900f1c3ab77700b284ae24fa8e8f7754f86f2282c795db6b0b17df1c29cc0552e59d01f7d777c638a813333277271c2f8b4d99d01ff0e6ee8695697bdd5b568089395620d7198c6093ce8bc59b928611b1b12452c05addaa42f4beff6a0a6fe90000000380d0dbc3f40210090402040005c801040205c8010500040004000e2003faf2cb329f2e90d6d23b58d91bbb6c046aa143261cc21f52fbe2824bfcbf04d807d601e4c6a70408d602b2a5730000d603e4c6a70601d604e4c6a7080ed605e4c6a70505d606e4c6a70705d60795720399c1a7c1720299c17202c1a7eb027201d1ededededededededed93c27202c2a793e4c672020408720193e4c6720205059572039d9c72057eb272047301000573029d9c72057eb2720473030005730494e4c672020601720393e4c672020705720693e4c67202080e720493e4c67202090ec5a79572039072079c720672059272079c72067205917207730595ef720393b1db630872027306d801d608b2db63087202730700ed938c7208017308938c7208027206c8df35000508cd030c8f9c4dc08f3c006fa85a47c9156dedbede000a8b764c6e374fd097e873ba0405c8a8c105010105dc8b020e0266608cdea8baf0380008cd030c8f9c4dc08f3c006fa85a47c9156dedbede000a8b764c6e374fd097e873ba04c8df350000c0843d1005040004000e36100204a00b08cd0279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798ea02d192a39a8cc7a701730073011001020402d19683030193a38cc7b2a57300000193c2b2a57301007473027303830108cdeeac93b1a57304c8df350000" } } } }, "responses": { "200": { "description": "JSON with ID of the new transaction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionId" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/transactions/unconfirmed": { "get": { "summary": "Get current pool of the unconfirmed transactions pool", "operationId": "getUnconfirmedTransactions", "tags": [ "transactions" ], "responses": { "200": { "description": "Array with Ergo transactions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionsWithInputBoxes" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/transactions/unconfirmed/{txId}": { "head": { "summary": "Check if given transaction is unconfirmed in pool", "operationId": "checkUnconfirmedTransaction", "tags": [ "transactions" ], "responses": { "200": { "description": "Transaction is in pool" }, "404": { "description": "Transaction is not in pool" } }, "parameters": [ { "in": "path", "name": "txId", "required": true, "schema": { "type": "string" } } ] } }, "/transactions/unconfirmed/byTransactionId/{txId}": { "get": { "summary": "Get unconfirmed transaction from pool", "operationId": "getUnconfirmedTransactionById", "tags": [ "transactions" ], "responses": { "200": { "description": "Ergo transaction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErgoTransactionWithInputBoxes" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "in": "path", "name": "txId", "required": true, "schema": { "type": "string" } } ] } }, "/transactions/unconfirmed/transactionIds": { "get": { "summary": "Get list of unconfirmed transactions ids", "operationId": "getUnconfirmedTxIds", "tags": [ "transactions" ], "responses": { "200": { "description": "List of unconfirmed transaction ids", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/transactions/unconfirmed/byTransactionIds": { "post": { "summary": "Get list of unconfirmed transactions by their ids", "operationId": "getUnconfirmedTxsByIds", "tags": [ "transactions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "responses": { "200": { "description": "List of unconfirmed transaction ids", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/transactions/unconfirmed/byErgoTree": { "post": { "summary": "Finds unconfirmed transactions by ErgoTree hex of one of its output or input boxes (if present in UtxoState)", "operationId": "getUnconfirmedTransactionsByErgoTree", "tags": [ "transactions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "string", "example": "100204a00b08cd021cf943317b0fdb50f60892a46b9132b9ced337c7de79248b104b293d9f1f078eea02d192a39a8cc7a70173007301" } } } }, "responses": { "200": { "description": "Ergo transaction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErgoTransactionWithInputBoxes" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/transactions/poolHistogram": { "get": { "summary": "Get histogram (waittime, (n_trans, sum(fee)) for transactions in mempool. It contains \"bins\"+1 bins, where i-th elements corresponds to transaction with wait time [i*maxtime/bins, (i+1)*maxtime/bins), and last bin corresponds to the transactions with wait time >= maxtime.", "operationId": "getFeeHistogram", "tags": [ "transactions" ], "responses": { "200": { "description": "Array with fee histogram", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeeHistogram" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/transactions/getFee": { "get": { "summary": "Get recommended fee (in nanoErgs) for a transaction with specified size (in bytes) to be proceeded in specified time (in minutes)", "operationId": "getRecommendedFee", "tags": [ "transactions" ], "responses": { "200": { "description": "Recommended fee for the transaction (in nanoErgs)", "content": { "application/json": { "schema": { "type": "integer" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/transactions/waitTime": { "get": { "summary": "Get expected wait time for the transaction with specified fee and size", "operationId": "getExpectedWaitTime", "tags": [ "transactions" ], "responses": { "200": { "description": "Expected wait time in milliseconds", "content": { "application/json": { "schema": { "type": "integer" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/peers/status": { "get": { "summary": "Get last incoming message timestamp and current network time", "operationId": "getPeersStatus", "tags": [ "peers" ], "responses": { "200": { "description": "Network status", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PeersStatus" } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/utxo/byId/{boxId}": { "get": { "summary": "Get box contents for a box by a unique identifier.", "operationId": "getBoxById", "tags": [ "utxo" ], "parameters": [ { "in": "path", "name": "boxId", "required": true, "description": "ID of a wanted box", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Box object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErgoTransactionOutput" } } } }, "404": { "description": "Box with this id doesn't exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/utxo/byIdBinary/{boxId}": { "get": { "summary": "Get serialized box from UTXO pool in Base16 encoding by an identifier.", "operationId": "getBoxByIdBinary", "tags": [ "utxo" ], "parameters": [ { "in": "path", "name": "boxId", "required": true, "description": "ID of a wanted box", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Json containing box identifier and hex-encoded box bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerializedBox" } } } }, "404": { "description": "Box with this id doesn't exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/utxo/withPool/byId/{boxId}": { "get": { "summary": "Get box contents for a box by a unique identifier, from UTXO set and also the mempool.", "operationId": "getBoxWithPoolById", "tags": [ "utxo" ], "parameters": [ { "in": "path", "name": "boxId", "required": true, "description": "ID of a box to obtain", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Box object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErgoTransactionOutput" } } } }, "404": { "description": "Box with this id doesn't exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/utxo/withPool/byIds": { "post": { "summary": "Get boxes for ids provided, from UTXO or the mempool.", "operationId": "getBoxWithPoolByIds", "tags": [ "utxo" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "responses": { "200": { "description": "Box object", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ErgoTransactionOutput" } } } } }, "404": { "description": "No any box exists for every id provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/utxo/withPool/byIdBinary/{boxId}": { "get": { "summary": "Get serialized box in Base16 encoding by an identifier, considering also the mempool.", "operationId": "getBoxWithPoolByIdBinary", "tags": [ "utxo" ], "parameters": [ { "in": "path", "name": "boxId", "required": true, "description": "ID of a wanted box", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Json containing box identifier and hex-encoded box bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerializedBox" } } } }, "404": { "description": "Box with this id doesn't exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/utxo/getSnapshotsInfo": { "get": { "summary": "Get information about locally stored UTXO snapshots", "description": "Serves the node's Mode-2 serve-side snapshot cache — at most one entry, rebuilt at each 52,224-block boundary on UTXO backends and held in memory only (empty at boot until the next boundary). The same view answers the P2P SnapshotsInfo message, so REST and wire always agree. Digest backend returns the standard /utxo 503 (Scala answers 404 there — part of the documented /utxo digest divergence).", "operationId": "getSnapshotsInfo", "tags": [ "utxo" ], "responses": { "200": { "description": "A list of saved snapshots", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SnapshotsInfo" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/utxo/genesis": { "get": { "summary": "Get genesis boxes (boxes existed before the very first block)", "operationId": "genesisBoxes", "tags": [ "utxo" ], "responses": { "200": { "description": "A list of all the genesis boxes", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ErgoTransactionOutput" } } } } }, "404": { "description": "Box with this id doesn't exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/blockchain/indexedHeight": { "get": { "summary": "Get current indexed block height. (The indexer has processed all blocks up to this height.)", "description": "Bypasses the runtime status gate; this is the single\n`/blockchain/*` route that always returns 200 even while the\nindexer is `Syncing` or `Halted`. Body conveys the status.\n", "operationId": "getIndexedHeight", "tags": [ "blockchain" ], "responses": { "200": { "description": "height of the indexer and full height plus runtime status", "content": { "application/json": { "schema": { "type": "object", "required": [ "indexedHeight", "fullHeight", "status" ], "properties": { "indexedHeight": { "type": "integer", "default": 0, "description": "highest block fully indexed (in-memory mirror; 0 on boot-time halt)" }, "fullHeight": { "type": "integer", "description": "chain's current bestFullBlockHeight" }, "status": { "type": "string", "enum": [ "syncing", "caughtUp", "halted" ], "description": "runtime indexer status (see indexer design spec §4.2)" }, "haltReason": { "type": "string", "enum": [ "db-corruption", "undo-missing", "section-missing", "input-missing", "schema-corruption" ], "description": "present iff status == halted (one of IndexerHaltReason variants)" } } } } } } } } }, "/blockchain/block/byHeaderId/{headerId}": { "get": { "summary": "Get an indexed block by its header ID.", "operationId": "getBlockByHeaderId", "tags": [ "blockchain" ], "parameters": [ { "in": "path", "name": "headerId", "required": true, "description": "The header ID of the block to retrieve.", "schema": { "$ref": "#/components/schemas/ModifierId" } } ], "responses": { "200": { "description": "The requested indexed block.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IndexedFullBlock" } } } }, "404": { "description": "A block with the specified header ID was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/blockchain/block/byHeaderIds": { "post": { "summary": "Get an array of indexed blocks by their header IDs.", "operationId": "getBlocksByHeaderIds", "tags": [ "blockchain" ], "requestBody": { "required": true, "description": "An array of header IDs to retrieve. The number of IDs is limited.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ModifierId" }, "example": [ "d16c21a48194480b57754980072d6507425f1647e6216a2a0a2569a9b0a701d1", "e569557a2f153a1e2898a3b2b415a9bf32b13b19b22a083f23a07747e93f7c4f" ] } } } }, "responses": { "200": { "description": "An array of the requested indexed blocks. The response will contain only the blocks that were found.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/IndexedFullBlock" } } } } }, "400": { "description": "The request is invalid, e.g., it contains too many header IDs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/blockchain/transaction/byId/{txId}": { "get": { "summary": "Retrieve a transaction by its id", "operationId": "getTxById", "tags": [ "blockchain" ], "parameters": [ { "in": "path", "name": "txId", "required": true, "description": "id of the wanted transaction", "schema": { "type": "string" } } ], "responses": { "200": { "description": "transaction with wanted id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IndexedErgoTransaction" } } } }, "404": { "description": "Transaction with this id doesn't exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/blockchain/transaction/byIndex/{txIndex}": { "get": { "summary": "Retrieve a transaction by global index number", "operationId": "getTxByIndex", "tags": [ "blockchain" ], "parameters": [ { "in": "path", "name": "txIndex", "required": true, "description": "index of the wanted transaction", "schema": { "type": "number" } } ], "responses": { "200": { "description": "transaction with wanted index", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IndexedErgoTransaction" } } } }, "404": { "description": "Transaction with this index doesn't exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/blockchain/transaction/byAddress": { "post": { "summary": "Retrieve transactions by their associated address", "operationId": "getTxsByAddress", "tags": [ "blockchain" ], "requestBody": { "required": true, "description": "address associated with transactions", "content": { "application/json": { "schema": { "type": "string", "example": "3WwbzW6u8hKWBcL1W7kNVMr25s2UHfSBnYtwSHvrRQt7DdPuoXrt" } } } }, "parameters": [ { "in": "query", "name": "offset", "required": false, "description": "amount of elements to skip from the start", "schema": { "type": "integer", "format": "int32", "default": 0 } }, { "in": "query", "name": "limit", "required": false, "description": "amount of elements to retrieve", "schema": { "type": "integer", "format": "int32", "default": 5 } } ], "responses": { "200": { "description": "transactions associated with wanted address", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "description": "Array of transactions", "items": { "$ref": "#/components/schemas/IndexedErgoTransaction" } }, "total": { "type": "integer", "description": "Total count of retrieved transactions" } } } } } }, "404": { "description": "No transactions found for wanted address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/blockchain/transaction/byAddress/{address}": { "get": { "summary": "Retrieve transactions by address (GET twin of /blockchain/transaction/byAddress)", "description": "Functionally identical to the POST form, but accepts the address\nas a path parameter instead of a JSON body. Mounted by Scala\nalongside the POST variant.\n", "operationId": "getTxsByAddressGet", "tags": [ "blockchain" ], "parameters": [ { "in": "path", "name": "address", "required": true, "description": "address associated with transactions", "schema": { "type": "string" } }, { "in": "query", "name": "offset", "required": false, "description": "amount of elements to skip from the start", "schema": { "type": "integer", "format": "int32", "default": 0 } }, { "in": "query", "name": "limit", "required": false, "description": "amount of elements to retrieve", "schema": { "type": "integer", "format": "int32", "default": 5 } } ], "responses": { "200": { "description": "transactions associated with wanted address", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "description": "Array of transactions", "items": { "$ref": "#/components/schemas/IndexedErgoTransaction" } }, "total": { "type": "integer", "description": "Total count of retrieved transactions" } } } } } }, "404": { "description": "No transactions found for wanted address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/blockchain/box/byId/{boxId}": { "get": { "summary": "Retrieve a box by its id", "operationId": "getIndexedBoxById", "tags": [ "blockchain" ], "parameters": [ { "in": "path", "name": "boxId", "required": true, "description": "id of the wanted box", "schema": { "type": "string" } } ], "responses": { "200": { "description": "box with wanted id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IndexedErgoBox" } } } }, "404": { "description": "No box found with wanted id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/blockchain/box/byIndex/{boxIndex}": { "get": { "summary": "Retrieve a box by global index number", "operationId": "getBoxByIndex", "tags": [ "blockchain" ], "parameters": [ { "in": "path", "name": "boxIndex", "required": true, "description": "index of the wanted box", "schema": { "type": "number" } } ], "responses": { "200": { "description": "box with wanted index", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IndexedErgoBox" } } } }, "404": { "description": "Box with this index doesn't exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/blockchain/box/byTokenId/{tokenId}": { "get": { "summary": "Retrieve boxes by an associated token id", "operationId": "getBoxesByTokenId", "tags": [ "blockchain" ], "parameters": [ { "in": "path", "name": "tokenId", "required": true, "description": "id of the token", "schema": { "$ref": "#/components/schemas/ModifierId" } }, { "in": "query", "name": "offset", "required": false, "description": "amount of elements to skip from the start", "schema": { "type": "integer", "format": "int32", "default": 0 } }, { "in": "query", "name": "limit", "required": false, "description": "amount of elements to retrieve", "schema": { "type": "integer", "format": "int32", "default": 5 } } ], "responses": { "200": { "description": "boxes associated with wanted token", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "description": "Array of boxes", "items": { "$ref": "#/components/schemas/IndexedErgoBox" } }, "total": { "type": "integer", "description": "Total number of retreived boxes" } } } } } }, "404": { "description": "No boxes found for wanted token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/blockchain/box/unspent/byTokenId/{tokenId}": { "get": { "summary": "Retrieve unspent boxes by an associated token id", "description": "Mempool overlay (P5, slice 6) is wired on this route per spec\n§3.6.1: `includeUnconfirmed` / `excludeMempoolSpent` are\nstrictly orthogonal. Pool outputs are matched by token-id\nmembership — a pool box matches if any entry in\n`box.candidate.tokens` has the queried `tokenId`, so\nmulti-token pool outputs match on any of their tokens.\nMatching pool outputs are appended with\n`inclusionHeight = 0` (the unique mempool sentinel) and\n`globalIndex = 0`. **Paging quirk (`[inherited]`):**\nconfirmed slicing happens before the unconfirmed merge, so\nwhen `includeUnconfirmed=true` the response can contain\n*more* than `limit` items.\n", "operationId": "getBoxesByTokenIdUnspent", "tags": [ "blockchain" ], "parameters": [ { "in": "path", "name": "tokenId", "required": true, "description": "id of the token", "schema": { "$ref": "#/components/schemas/ModifierId" } }, { "in": "query", "name": "offset", "required": false, "description": "amount of elements to skip from the start", "schema": { "type": "integer", "format": "int32", "default": 0 } }, { "in": "query", "name": "limit", "required": false, "description": "amount of elements to retrieve", "schema": { "type": "integer", "format": "int32", "default": 5 } }, { "in": "query", "name": "sortDirection", "required": false, "description": "desc = new boxes first ; asc = old boxes first", "schema": { "type": "string", "default": "desc" } }, { "in": "query", "name": "includeUnconfirmed", "required": false, "description": "if true include unconfirmed transactions from mempool", "schema": { "type": "boolean", "default": false } }, { "in": "query", "name": "excludeMempoolSpent", "required": false, "description": "if true exclude spent inputs from mempool", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "unspent boxes associated with wanted token", "content": { "application/json": { "schema": { "type": "array", "description": "Array of boxes", "items": { "$ref": "#/components/schemas/IndexedErgoBox" } } } } }, "404": { "description": "No unspent boxes found for wanted token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/blockchain/box/byAddress": { "post": { "summary": "Retrieve boxes by their associated address", "operationId": "getBoxesByAddress", "tags": [ "blockchain" ], "requestBody": { "description": "address associated with boxes", "required": true, "content": { "application/json": { "schema": { "type": "string", "example": "3WwbzW6u8hKWBcL1W7kNVMr25s2UHfSBnYtwSHvrRQt7DdPuoXrt" } } } }, "parameters": [ { "in": "query", "name": "offset", "required": false, "description": "amount of elements to skip from the start", "schema": { "type": "integer", "format": "int32", "default": 0 } }, { "in": "query", "name": "limit", "required": false, "description": "amount of elements to retrieve", "schema": { "type": "integer", "format": "int32", "default": 5 } } ], "responses": { "200": { "description": "boxes associated with wanted address", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "description": "Array of boxes", "items": { "$ref": "#/components/schemas/IndexedErgoBox" } }, "total": { "type": "integer", "description": "Total number of retreived boxes" } } } } } }, "404": { "description": "No boxes found for wanted address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/blockchain/box/byAddress/{address}": { "get": { "summary": "Retrieve boxes by address (GET twin of /blockchain/box/byAddress)", "description": "Functionally identical to the POST form, but accepts the address\nas a path parameter instead of a JSON body. Mounted by Scala\nalongside the POST variant.\n", "operationId": "getBoxesByAddressGet", "tags": [ "blockchain" ], "parameters": [ { "in": "path", "name": "address", "required": true, "description": "address associated with boxes", "schema": { "type": "string" } }, { "in": "query", "name": "offset", "required": false, "description": "amount of elements to skip from the start", "schema": { "type": "integer", "format": "int32", "default": 0 } }, { "in": "query", "name": "limit", "required": false, "description": "amount of elements to retrieve", "schema": { "type": "integer", "format": "int32", "default": 5 } } ], "responses": { "200": { "description": "boxes associated with wanted address", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "description": "Array of boxes", "items": { "$ref": "#/components/schemas/IndexedErgoBox" } }, "total": { "type": "integer", "description": "Total number of retreived boxes" } } } } } }, "404": { "description": "No boxes found for wanted address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/blockchain/box/unspent/byAddress": { "post": { "summary": "Retrieve unspent boxes by their associated address", "description": "Mempool overlay (P5, slice 4) is wired on this route per spec\n§3.6.1: `includeUnconfirmed` / `excludeMempoolSpent` are\nstrictly orthogonal. Pool outputs matching the queried address\nare appended with `inclusionHeight = 0` (the unique mempool\nsentinel) and `globalIndex = 0`. **Paging quirk\n(`[inherited]`):** confirmed slicing happens before the\nunconfirmed merge, so when `includeUnconfirmed=true` the\nresponse can contain *more* than `limit` items (up to `limit +\n|pool_outputs|`). This is upstream Scala behavior; clients that\ndepend on `result.length <= limit` must update.\n", "operationId": "getBoxesByAddressUnspent", "tags": [ "blockchain" ], "requestBody": { "description": "address associated with unspent boxes", "required": true, "content": { "application/json": { "schema": { "type": "string", "example": "3WwbzW6u8hKWBcL1W7kNVMr25s2UHfSBnYtwSHvrRQt7DdPuoXrt" } } } }, "parameters": [ { "in": "query", "name": "offset", "required": false, "description": "amount of elements to skip from the start", "schema": { "type": "integer", "format": "int32", "default": 0 } }, { "in": "query", "name": "limit", "required": false, "description": "amount of elements to retrieve", "schema": { "type": "integer", "format": "int32", "default": 5 } }, { "in": "query", "name": "sortDirection", "required": false, "description": "desc = new boxes first ; asc = old boxes first", "schema": { "type": "string", "default": "desc" } }, { "in": "query", "name": "includeUnconfirmed", "required": false, "description": "if true include unconfirmed transactions from mempool", "schema": { "type": "boolean", "default": false } }, { "in": "query", "name": "excludeMempoolSpent", "required": false, "description": "if true exclude spent inputs from mempool", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "unspent boxes associated with wanted address", "content": { "application/json": { "schema": { "type": "array", "description": "Array of boxes", "items": { "$ref": "#/components/schemas/IndexedErgoBox" } } } } }, "404": { "description": "No unspent boxes found for wanted address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/blockchain/box/unspent/byAddress/{address}": { "get": { "summary": "Retrieve unspent boxes by address (GET twin of /blockchain/box/unspent/byAddress)", "description": "Functionally identical to the POST form, but accepts the address\nas a path parameter instead of a JSON body. Mounted by Scala\nalongside the POST variant. The same P5 mempool overlay\nsemantics and `[inherited]` paging quirk apply — see the POST\nendpoint description for details.\n", "operationId": "getBoxesByAddressUnspentGet", "tags": [ "blockchain" ], "parameters": [ { "in": "path", "name": "address", "required": true, "description": "address associated with unspent boxes", "schema": { "type": "string" } }, { "in": "query", "name": "offset", "required": false, "description": "amount of elements to skip from the start", "schema": { "type": "integer", "format": "int32", "default": 0 } }, { "in": "query", "name": "limit", "required": false, "description": "amount of elements to retrieve", "schema": { "type": "integer", "format": "int32", "default": 5 } }, { "in": "query", "name": "sortDirection", "required": false, "description": "desc = new boxes first ; asc = old boxes first", "schema": { "type": "string", "default": "desc" } }, { "in": "query", "name": "includeUnconfirmed", "required": false, "description": "if true include unconfirmed transactions from mempool", "schema": { "type": "boolean", "default": false } }, { "in": "query", "name": "excludeMempoolSpent", "required": false, "description": "if true exclude spent inputs from mempool", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "unspent boxes associated with wanted address", "content": { "application/json": { "schema": { "type": "array", "description": "Array of boxes", "items": { "$ref": "#/components/schemas/IndexedErgoBox" } } } } }, "404": { "description": "No unspent boxes found for wanted address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/blockchain/box/byTemplateHash/{hash}": { "get": { "summary": "Retrieve boxes by their contract template hash", "operationId": "getBoxesByTemplateHash", "tags": [ "blockchain" ], "parameters": [ { "in": "path", "name": "hash", "required": true, "description": "blake2b256 hash of an ErgoTree template encoded in base 16", "schema": { "$ref": "#/components/schemas/ModifierId" } }, { "in": "query", "name": "offset", "required": false, "description": "amount of elements to skip from the start", "schema": { "type": "integer", "format": "int32", "default": 0 } }, { "in": "query", "name": "limit", "required": false, "description": "amount of elements to retrieve", "schema": { "type": "integer", "format": "int32", "default": 5 } } ], "responses": { "200": { "description": "Boxes with the wanted template hash. Unknown templates return\nthis 200 envelope with `items: []` and `total: 0` (Scala\nfalls back to an empty `IndexedContractTemplate(hash)` rather\nthan 404 — see spec §8.6).\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "description": "Array of boxes", "items": { "$ref": "#/components/schemas/IndexedErgoBox" } }, "total": { "type": "integer", "description": "Total number of boxes for this template hash" } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/blockchain/box/unspent/byTemplateHash/{hash}": { "get": { "summary": "Retrieve unspent boxes by their contract template hash", "description": "Mempool overlay (P5, slice 5) is wired on this route per spec\n§3.6.1: `includeUnconfirmed` / `excludeMempoolSpent` are\nstrictly orthogonal. Pool outputs whose\n`template_hash_from_bytes(tree_bytes)` matches the queried hash\nare appended with `inclusionHeight = 0` (the unique mempool\nsentinel) and `globalIndex = 0`. Soft-fork-wrapped trees in the\npool are skipped — Scala's `IndexedContractTemplate` only records\ntemplate hashes for parseable trees, so a wrapped pool output\ncannot match any queried template. **Paging quirk\n(`[inherited]`):** confirmed slicing happens before the\nunconfirmed merge, so when `includeUnconfirmed=true` the response\ncan contain *more* than `limit` items.\n", "operationId": "getBoxesByTemplateHashUnspent", "tags": [ "blockchain" ], "parameters": [ { "in": "path", "name": "hash", "required": true, "description": "blake2b256 hash of an ErgoTree template encoded in base 16", "schema": { "$ref": "#/components/schemas/ModifierId" } }, { "in": "query", "name": "offset", "required": false, "description": "amount of elements to skip from the start", "schema": { "type": "integer", "format": "int32", "default": 0 } }, { "in": "query", "name": "limit", "required": false, "description": "amount of elements to retrieve", "schema": { "type": "integer", "format": "int32", "default": 5 } }, { "in": "query", "name": "sortDirection", "required": false, "description": "desc = new boxes first ; asc = old boxes first", "schema": { "type": "string", "default": "desc" } }, { "in": "query", "name": "includeUnconfirmed", "required": false, "description": "if true include unconfirmed transactions from mempool", "schema": { "type": "boolean", "default": false } }, { "in": "query", "name": "excludeMempoolSpent", "required": false, "description": "if true exclude spent inputs from mempool", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Unspent boxes with the wanted template hash. Unknown templates\nreturn this 200 envelope with an empty array (Scala falls back\nto an empty `IndexedContractTemplate(hash)` rather than 404 —\nsee spec §8.6).\n", "content": { "application/json": { "schema": { "type": "array", "description": "Array of boxes", "items": { "$ref": "#/components/schemas/IndexedErgoBox" } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/blockchain/box/byErgoTree": { "post": { "summary": "Retrieve boxes by their associated ergotree", "operationId": "getBoxesByErgoTree", "tags": [ "blockchain" ], "requestBody": { "required": true, "description": "hex encoded ergotree", "content": { "application/json": { "schema": { "type": "string", "example": "100204a00b08cd021cf943317b0fdb50f60892a46b9132b9ced337c7de79248b104b293d9f1f078eea02d192a39a8cc7a70173007301" } } } }, "parameters": [ { "in": "query", "name": "offset", "required": false, "description": "amount of elements to skip from the start", "schema": { "type": "integer", "format": "int32", "default": 0 } }, { "in": "query", "name": "limit", "required": false, "description": "amount of elements to retrieve", "schema": { "type": "integer", "format": "int32", "default": 5 } } ], "responses": { "200": { "description": "boxes with wanted ergotree", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "description": "Array of boxes", "items": { "$ref": "#/components/schemas/IndexedErgoBox" } }, "total": { "type": "integer", "description": "Total number of retreived boxes" } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/blockchain/box/unspent/byErgoTree": { "post": { "summary": "Retrieve unspent boxes by their associated ergotree", "description": "Mempool overlay (P5, slice 7) is wired on this route per spec\n§3.6.1: `includeUnconfirmed` / `excludeMempoolSpent` are\nstrictly orthogonal. The body's hex-encoded ergotree is\nre-serialized and blake2b256-hashed; the resulting tree_hash\nis the same key the address-keyed indexer tables use, so the\noverlay is byte-identical to `/blockchain/box/unspent/byAddress`\n(slice 4): pool outputs whose canonical\n`tree_hash_from_bytes(tree_bytes)` matches the queried hash\nare appended with `inclusionHeight = 0` (the unique mempool\nsentinel) and `globalIndex = 0`. **Paging quirk\n(`[inherited]`):** confirmed slicing happens before the\nunconfirmed merge, so when `includeUnconfirmed=true` the\nresponse can contain *more* than `limit` items.\n", "operationId": "getBoxesByErgoTreeUnspent", "tags": [ "blockchain" ], "requestBody": { "description": "hex encoded ergotree", "required": true, "content": { "application/json": { "schema": { "type": "string", "example": "100204a00b08cd021cf943317b0fdb50f60892a46b9132b9ced337c7de79248b104b293d9f1f078eea02d192a39a8cc7a70173007301" } } } }, "parameters": [ { "in": "query", "name": "offset", "required": false, "description": "amount of elements to skip from the start", "schema": { "type": "integer", "format": "int32", "default": 0 } }, { "in": "query", "name": "limit", "required": false, "description": "amount of elements to retrieve", "schema": { "type": "integer", "format": "int32", "default": 5 } }, { "in": "query", "name": "sortDirection", "required": false, "description": "desc = new boxes first ; asc = old boxes first", "schema": { "type": "string", "default": "desc" } }, { "in": "query", "name": "includeUnconfirmed", "required": false, "description": "if true include unconfirmed transactions from mempool", "schema": { "type": "boolean", "default": false } }, { "in": "query", "name": "excludeMempoolSpent", "required": false, "description": "if true exclude spent inputs from mempool", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Unspent boxes with wanted ergotree. Returns an empty array\n(`[]`, never 404) when no boxes match — this matches Scala's\nunspent-route convention across `byAddress`/`byTemplateHash`/\n`byTokenId`/`byErgoTree`.\n", "content": { "application/json": { "schema": { "type": "array", "description": "Array of boxes", "items": { "$ref": "#/components/schemas/IndexedErgoBox" } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/blockchain/token/byId/{tokenId}": { "get": { "summary": "Retrieve minting information about a token", "operationId": "getTokenById", "tags": [ "blockchain" ], "parameters": [ { "in": "path", "name": "tokenId", "required": true, "description": "id of the wanted token", "schema": { "type": "string" } } ], "responses": { "200": { "description": "token with wanted id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IndexedToken" } } } }, "404": { "description": "No token found with wanted id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/blockchain/tokens": { "post": { "summary": "Retrieve minting information about a list of tokens", "operationId": "getTokensByIds", "tags": [ "blockchain" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string", "description": "Token ID" } } } } }, "responses": { "200": { "description": "Array of tokens with the provided IDs", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/IndexedToken" } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/blockchain/balance": { "post": { "summary": "Retrieve confirmed and unconfirmed balance of an address", "description": "`unconfirmed` is computed *strictly additively* from mempool\ntransaction outputs whose ergoTree hashes to the queried address —\nit never subtracts mempool-spent confirmed boxes from `confirmed`,\nand it does not traverse mempool-chained spends. This is\n`[inherited]` parity with Scala\n`BlockchainApiRoute.getUnconfirmedForAddress`\n(`BlockchainApiRoute.scala:444-451`). A user with\n`confirmed = 100 ERG` who submits a mempool tx spending all\n100 ERG will see `confirmed = 100, unconfirmed = 0` here, even\nthough their spendable balance is 0. Wallets needing true\nspendable balance under mempool pressure should compute it\nclient-side via\n`/blockchain/box/unspent/byAddress?excludeMempoolSpent=true&includeUnconfirmed=true`.\n\nToken aggregation in `unconfirmed.tokens` is sorted by `tokenId`\nhex for deterministic wire shape across snapshot rebuilds; the\n`confirmed.tokens` order remains insertion-ordered as projected\nby the indexer.\n", "operationId": "getAddressBalanceTotal", "tags": [ "blockchain" ], "requestBody": { "description": "address with balance", "required": true, "content": { "application/json": { "schema": { "type": "string", "example": "\"3WwbzW6u8hKWBcL1W7kNVMr25s2UHfSBnYtwSHvrRQt7DdPuoXrt\"" } } } }, "responses": { "200": { "description": "balance information", "content": { "application/json": { "schema": { "type": "object", "required": [ "confirmed", "unconfirmed" ], "properties": { "confirmed": { "$ref": "#/components/schemas/BalanceInfo" }, "unconfirmed": { "$ref": "#/components/schemas/BalanceInfo" } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/blockchain/balanceForAddress/{address}": { "get": { "summary": "Retrieve balance by address (GET twin of /blockchain/balance)", "description": "Functionally identical to the POST form, but accepts the address\nas a path parameter instead of a JSON body. Mounted by Scala\nalongside the POST variant. The `[inherited]` strictly-additive\n`unconfirmed` semantics match `/blockchain/balance` —\nunconfirmed never subtracts mempool-spent confirmed boxes.\nSee the POST variant's description for the full caveat.\n", "operationId": "getAddressBalanceTotalGet", "tags": [ "blockchain" ], "parameters": [ { "in": "path", "name": "address", "required": true, "description": "address whose balance is being queried", "schema": { "type": "string" } } ], "responses": { "200": { "description": "balance information", "content": { "application/json": { "schema": { "type": "object", "required": [ "confirmed", "unconfirmed" ], "properties": { "confirmed": { "$ref": "#/components/schemas/BalanceInfo" }, "unconfirmed": { "$ref": "#/components/schemas/BalanceInfo" } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } } }, "security": [] }