Koios-API/KoiosAPI-codegemma-7b-it
0
1openapi: 3.1.02info:3 title: Koios API4 contact:5 name: Koios Core Team6 url: https://t.me/CardanoKoios7 email: general@koios.rest8 license:9 name: Creative Commons Attribution 4.0 International10 url: https://github.com/cardano-community/koios-artifacts/blob/main/LICENSE11 version: v1.1.012 description: >13 Koios is best described as a Decentralized and Elastic RESTful query layer for exploring data on Cardano blockchain to consume within applications/wallets/explorers/etc. This page not only provides an OpenAPI Spec for live implementation, but also ability to execute live demo from client browser against each endpoint with pre-filled examples.14 15 # API Usage16 17 The endpoints served by Koios can be browsed from the left side bar of this site. You will find that almost each endpoint has an example that you can `Try` and will help you get an example in shell using cURL. For public queries, you do not need to register yourself - you can simply use them as per the examples provided on individual endpoints. But in addition, the [PostgREST API](https://postgrest.org/en/stable/api.html) used underneath provides a handful of features that can be quite handy for you to improve your queries to directly grab very specific information pertinent to your calls, reducing data you download and process.18 19 20 ## Vertical Filtering21 22 23 Instead of returning entire row, you can elect which rows you would like to fetch from the endpoint by using the `select` parameter with corresponding columns separated by commas. See example below (first is complete information for tip, while second command gives us 3 columns we are interested in):<br><br>24 25 26 ``` bash27 28 curl "https://api.koios.rest/api/v1/tip"29 30 31 # [{"hash":"4d44c8a453e677f933c3df42ebcf2fe45987c41268b9cfc9b42ae305e8c3d99a","epoch":317,"abs_slot":51700871,"epoch_slot":120071,"block_height":6806994,"block_time":1643267162}]32 33 34 curl "https://api.koios.rest/api/v1/blocks?select=epoch,epoch_slot,block_height"35 36 37 # [{"epoch":317,"epoch_slot":120071,"block_height":6806994}]38 39 ```40 41 ## Horizontal Filtering42 43 You can filter the returned output based on specific conditions using operators against a column within returned result. Consider an example where you would want to query blocks minted in first 3 minutes of epoch 250 (i.e. epoch_slot was less than 180). To do so your query would look like below:<br><br>44 45 ``` bash46 47 curl "https://api.koios.rest/api/v1/blocks?epoch=eq.250&epoch_slot=lt.180"48 49 50 # [{"hash":"8fad2808ac6b37064a0fa69f6fe065807703d5235a57442647bbcdba1c02faf8","epoch":250,"abs_slot":22636942,"epoch_slot":142,"block_height":5385757,"block_time":1614203233,"tx_count":65,"vrf_key":"vrf_vk14y9pjprzlsjvjt66mv5u7w7292sxp3kn4ewhss45ayjga5vurgaqhqknuu","pool":null,"op_cert_counter":2},51 52 # {"hash":"9d33b02badaedc0dedd0d59f3e0411e5fb4ac94217fb5ee86719e8463c570e16","epoch":250,"abs_slot":22636800,"epoch_slot":0,"block_height":5385756,"block_time":1614203091,"tx_count":10,"vrf_key":"vrf_vk1dkfsejw3h2k7tnguwrauqfwnxa7wj3nkp3yw2yw3400c4nlkluwqzwvka6","pool":null,"op_cert_counter":2}]53 54 ```55 56 57 Here, we made use of `eq.` operator to denote a filter of "value equal to" against `epoch` column. Similarly, we added a filter using `lt.` operator to denote a filter of "values lower than" against `epoch_slot` column. You can find a complete list of operators supported in PostgREST documentation (commonly used ones extracted below):58 59 60 |Abbreviation|In PostgreSQL|Meaning |61 62 |------------|-------------|-------------------------------------------|63 64 |eq |`=` |equals |65 66 |gt |`>` |greater than |67 68 |gte |`>=` |greater than or equal |69 70 |lt |`<` |less than |71 72 |lte |`<=` |less than or equal |73 74 |neq |`<>` or `!=` |not equal |75 76 |like |`LIKE` |LIKE operator (use * in place of %) |77 78 |in |`IN` |one of a list of values, e.g. `?a=in.("hi,there","yes,you")`|79 80 |is |`IS` |checking for exact equality (null,true,false,unknown)|81 82 |cs |`@>` |contains e.g. `?tags=cs.{example, new}` |83 84 |cd |`<@` |contained in e.g. `?values=cd.{1,2,3}` |85 86 |not |`NOT` |negates another operator |87 88 |or |`OR` |logical `OR` operator |89 90 |and |`AND` |logical `AND` operator |91 92 93 ## Pagination (offset/limit)94 95 96 When you query any endpoint in PostgREST, the number of observations returned will be limited to a maximum of 1000 rows (set via `max-rows` config option in the `grest.conf` file. This - however - is a result of a paginated call, wherein the [ up to ] 1000 records you see without any parameters is the first page. If you want to see the next 1000 results, you can always append `offset=1000` to view the next set of results. But what if 1000 is too high for your use-case and you want smaller page? Well, you can specify a smaller limit using parameter `limit`, which will see shortly in an example below. The obvious question at this point that would cross your mind is - how do I know if I need to offset and what range I am querying? This is where headers come in to your aid. 97 98 99 The default headers returned by PostgREST will include a `Content-Range` field giving a range of observations returned. For large tables, this range could include a wildcard `*` as it is expensive to query exact count of observations from endpoint. But if you would like to get an estimate count without overloading servers, PostgREST can utilise Postgres's own maintenance thread results (which maintain stats for each table) to provide you a count, by specifying a header `"Preferred: count=estimated"`. 100 101 102 Sounds confusing? Let's see this in practice, to hopefully make it easier.103 104 Consider a simple case where I want query `blocks` endpoint for `block_height` column and focus on `content-range` header to monitor the rows we discussed above.<br><br>105 106 107 ``` bash108 109 curl -s "https://api.koios.rest/api/v1/blocks?select=block_height" -I | grep -i content-range110 111 112 # content-range: 0-999/*113 114 115 ```116 117 118 As we can see above, the number of observations returned was 1000 (range being 0-999), but the total size was not queried to avoid wait times. Now, let's modify this default behaviour to query rows beyond the first 999, but this time - also add another clause to limit results by 500. We can do this using `offset=1000` and `limit=500` as below:<br><br>119 120 121 ``` bash122 123 curl -s "https://api.koios.rest/api/v1/blocks?select=block_height&offset=1000&limit=500" -I | grep -i content-range124 125 126 # content-range: 1000-1499/*127 128 129 ```130 131 132 For GET endpoints, there is also another method to achieve the above, instead of adding parameters to the URL itself, you can specify a `Range` header as below to achieve something similar:<br><br>133 134 135 ``` bash136 137 curl -s "https://api.koios.rest/api/v1/blocks?select=block_height" -H "Range: 1000-1499" -I | grep -i content-range138 139 140 # content-range: 1000-1499/*141 142 143 ```144 145 146 The above methods for pagination are very useful to keep your queries light as well as process the output in smaller pages, making better use of your resources and respecting server timeouts for response times.147 148 149 ## Ordering150 151 152 You can set a sorting order for returned queries against specific column(s).153 154 Consider example where you want to check `epoch` and `epoch_slot` for the first 5 blocks created by a particular pool, i.e. you can set order to ascending based on block_height column and add horizontal filter for that pool ID as below:<br><br>155 156 157 ``` bash158 159 curl -s "https://api.koios.rest/api/v1/blocks?pool=eq.pool155efqn9xpcf73pphkk88cmlkdwx4ulkg606tne970qswczg3asc&order=block_height.asc&limit=5"160 161 162 # [{"hash":"610b4c7bbebeeb212bd002885048cc33154ba29f39919d62a3d96de05d315706","epoch":236,"abs_slot":16594295,"epoch_slot":5495,"block_height":5086774,"block_time":1608160586,"tx_count":1,"vrf_key":"vrf_vk18x0e7dx8j37gdxftnn8ru6jcxs7n6acdazc4ykeda2ygjwg9a7ls7ns699","pool":"pool155efqn9xpcf73pphkk88cmlkdwx4ulkg606tne970qswczg3asc","op_cert_counter":1},163 164 # {"hash":"d93d1db5275329ab695d30c06a35124038d8d9af64fc2b0aa082b8aa43da4164","epoch":236,"abs_slot":16597729,"epoch_slot":8929,"block_height":5086944,"block_time":1608164020,"tx_count":7,"vrf_key":"vrf_vk18x0e7dx8j37gdxftnn8ru6jcxs7n6acdazc4ykeda2ygjwg9a7ls7ns699","pool":"pool155efqn9xpcf73pphkk88cmlkdwx4ulkg606tne970qswczg3asc","op_cert_counter":1},165 166 # {"hash":"dc9496eae64294b46f07eb20499ae6dae4d81fdc67c63c354397db91bda1ee55","epoch":236,"abs_slot":16598058,"epoch_slot":9258,"block_height":5086962,"block_time":1608164349,"tx_count":1,"vrf_key":"vrf_vk18x0e7dx8j37gdxftnn8ru6jcxs7n6acdazc4ykeda2ygjwg9a7ls7ns699","pool":"pool155efqn9xpcf73pphkk88cmlkdwx4ulkg606tne970qswczg3asc","op_cert_counter":1},167 168 # {"hash":"6ebc7b734c513bc19290d96ca573a09cac9503c5a349dd9892b9ab43f917f9bd","epoch":236,"abs_slot":16601491,"epoch_slot":12691,"block_height":5087097,"block_time":1608167782,"tx_count":0,"vrf_key":"vrf_vk18x0e7dx8j37gdxftnn8ru6jcxs7n6acdazc4ykeda2ygjwg9a7ls7ns699","pool":"pool155efqn9xpcf73pphkk88cmlkdwx4ulkg606tne970qswczg3asc","op_cert_counter":1},169 170 # {"hash":"2eac97548829fc312858bc56a40f7ce3bf9b0ca27ee8530283ccebb3963de1c0","epoch":236,"abs_slot":16602308,"epoch_slot":13508,"block_height":5087136,"block_time":1608168599,"tx_count":1,"vrf_key":"vrf_vk18x0e7dx8j37gdxftnn8ru6jcxs7n6acdazc4ykeda2ygjwg9a7ls7ns699","pool":"pool155efqn9xpcf73pphkk88cmlkdwx4ulkg606tne970qswczg3asc","op_cert_counter":1}]171 172 ```173 174 175 ## Response Formats176 177 178 You can get the results from the PostgREST endpoints in CSV or JSON formats. The default response format will always be JSON, but if you'd like to switch, you can do so by specifying header `'Accept: text/csv'` or `'Accept: application/json'`.179 180 Below is an example of JSON/CSV output making use of above to print first in JSON (default), and then override response format to CSV.<br><br>181 182 183 ``` bash184 185 curl -s "https://api.koios.rest/api/v1/blocks?select=epoch,epoch_slot,block_time&limit=3"186 187 188 # [{"epoch":318,"epoch_slot":27867,"block_time":1643606958},189 190 # {"epoch":318,"epoch_slot":27841,"block_time":1643606932},191 192 # {"epoch":318,"epoch_slot":27839,"block_time":1643606930}]193 194 195 curl -s "https://api.koios.rest/api/v1/blocks?select=epoch,epoch_slot,block_time&limit=3" -H "Accept: text/csv"196 197 198 # epoch,epoch_slot,block_time199 200 # 318,28491,1643607582201 202 # 318,28479,1643607570203 204 # 318,28406,1643607497205 206 207 ```208 209 210 ## Limits211 212 213 While use of Koios is completely free and there are no registration requirements to the usage, the monitoring layer will only restrict spam requests that can potentially cause high amount of load to backends. The emphasis is on using list of objects first, and then [bulk where available] query specific objects to drill down where possible - which forms higher performance results to consumer as well as instance provider. Some basic protection against patterns that could cause unexpected resource spikes are protected as per below:214 215 - Burst Limit: A single IP can query an endpoint up to 100 times within 10 seconds (that's about 8.64 million requests within a day). The sleep time if a limit is crossed is minimal (60 seconds) for that IP - during which, the monitoring layer will return HTTP Status `429 - Too many requests`. 216 - Pagination/Limits: Any query results fetched will be paginated by 1000 records (you can reduce limit and or control pagination offsets on URL itself, see API > Pagination section for more details).217 - Query timeout: If a query from server takes more than 30 seconds, it will return a HTTP Status of `504 - Gateway timeout`. This is because we would want to ensure you're using the queries optimally, and more often than not - it would indicate that particular endpoint is not optimised (or the network connectivity is not optimal between servers).218 219 Yet, there may be cases where the above restrictions may need exceptions (for example, an explorer or a wallet might need more connections than above - going beyond the Burst Limit). For such cases, it is best to approach the team and we can work towards a solution.220 221 222 # Authentication223 224 225 While Koios public tier remains unauthenticated and allows queries without any authentication, it has low limits to prevent actions against an erroraneous query/loop from a consumer. There is also a Free tier which requires setting up Bearer Auth token that is linked to the owner's wallet account (which can be connected to via [Koios website](https://koios.rest/pricing/Pricing.html) ).226 227 The examples across this API site already [supports authentication](/#auth), for you to use in the queries.228 229 230 # Community projects231 232 233 A big thank you to the following projects who are already starting to use Koios from early days. A list of tools, libraries and projects utilising Koios (atleast those who'd like to be named) can be found [here](https://www.koios.rest/community.html)234 x-logo:235 url: https://api.koios.rest/images/koios.png236servers:237 - url: https://api.koios.rest/api/v1238paths:239 /tip:240 get:241 tags:242 - Network243 responses:244 "200":245 description: Success!!246 content:247 application/json:248 schema:249 $ref: "#/components/schemas/tip"250 "400":251 $ref: "#/components/responses/BadRequest"252 "401":253 $ref: "#/components/responses/Unauthorized"254 "404":255 $ref: "#/components/responses/NotFound"256 summary: Query Chain Tip257 description: Get the tip info about the latest block seen by chain258 operationId: tip259 /genesis:260 get:261 tags:262 - Network263 responses:264 "200":265 description: Success!!266 content:267 application/json:268 schema:269 $ref: "#/components/schemas/genesis"270 "400":271 $ref: "#/components/responses/BadRequest"272 "401":273 $ref: "#/components/responses/Unauthorized"274 "404":275 $ref: "#/components/responses/NotFound"276 summary: Get Genesis info277 description: Get the Genesis parameters used to start specific era on chain278 operationId: genesis279 /totals:280 get:281 tags:282 - Network283 summary: Get historical tokenomic stats284 description: >-285 Get the circulating utxo, treasury, rewards, supply, and reserves in lovelace for the specified epoch. Returns data for all epochs if the epoch number is not provided.286 operationId: totals287 parameters:288 - in: query289 name: _epoch_no290 required: true291 schema:292 type: string293 description: Epoch number (required to get specific epoch data).294 responses:295 '200':296 description: Success!!297 content:298 application/json:299 schema:300 $ref: '#/components/schemas/totals'301 '400':302 $ref: '#/components/responses/BadRequest'303 '401':304 $ref: '#/components/responses/Unauthorized'305 '404':306 $ref: '#/components/responses/NotFound'307 /param_updates:308 get:309 tags:310 - Network311 responses:312 "200":313 description: Success!!314 content:315 application/json:316 schema:317 $ref: "#/components/schemas/param_updates"318 "400":319 $ref: "#/components/responses/BadRequest"320 "401":321 $ref: "#/components/responses/Unauthorized"322 "404":323 $ref: "#/components/responses/NotFound"324 summary: Param Update Proposals325 description: Get all parameter update proposals submitted to the chain starting Shelley era326 operationId: param_updates327 /reserve_withdrawals:328 get:329 tags:330 - Network331 parameters:332 - in: query333 name: epoch_no334 description: |335 Filter blocks by epoch. Use "epoch_no=eq.{value}" to filter by an exact match.336 If not specified, the API defaults to "eq.{epoch_no}" where {epoch_no} is the latest epoch fetched from the /tip endpoint.337 required: false338 schema:339 type: string340 default: "eq.450"341 example: "eq.450"342 - in: query343 name: limit344 required: true345 schema:346 type: number347 default: "5"348 example: "15"349 responses:350 "200":351 description: Success!!352 content:353 application/json:354 schema:355 $ref: "#/components/schemas/reserve_withdrawals"356 "400":357 $ref: "#/components/responses/BadRequest"358 "401":359 $ref: "#/components/responses/Unauthorized"360 "404":361 $ref: "#/components/responses/NotFound"362 summary: Reserve Withdrawals363 description: List of all withdrawals from reserves against stake accounts364 operationId: reserve_withdrawals365 /treasury_withdrawals:366 get:367 tags:368 - Network369 responses:370 "200":371 description: Success!!372 content:373 application/json:374 schema:375 $ref: "#/components/schemas/reserve_withdrawals"376 "400":377 $ref: "#/components/responses/BadRequest"378 "401":379 $ref: "#/components/responses/Unauthorized"380 "404":381 $ref: "#/components/responses/NotFound"382 parameters:383 - in: query384 name: epoch_no385 description: |386 Filter blocks by epoch. Use "epoch_no=eq.{value}" to filter by an exact match.387 If not specified, the API defaults to "eq.{epoch_no}" where {epoch_no} is the latest epoch fetched from the /tip endpoint.388 required: false389 schema:390 type: string391 default: "eq.450"392 example: "eq.450"393 - in: query394 name: limit395 required: true396 schema:397 type: number398 default: "5"399 example: "15"400 summary: Treasury Withdrawals401 description: List of all withdrawals from treasury against stake accounts402 operationId: treasury_withdrawals403 /epoch_info:404 get:405 tags:406 - Epoch407 parameters:408 - in: query409 name: _epoch_no410 required: true411 schema:412 type: string413 description: Epoch number (required to get specific epoch data).414 - in: query415 name: include_next_epoch416 description: Include details of the next epoch if available.417 schema:418 type: boolean419 responses:420 "200":421 description: Success!!422 content:423 application/json:424 schema:425 type: object426 properties:427 id:428 type: integer429 description: Unique identifier for the epoch.430 startDate:431 type: string432 format: date-time433 description: Start date and time of the epoch.434 endDate:435 type: string436 format: date-time437 description: End date and time of the epoch.438 status:439 type: string440 description: Current status of the epoch.441 "400":442 $ref: "#/components/responses/BadRequest"443 "401":444 $ref: "#/components/responses/Unauthorized"445 "404":446 $ref: "#/components/responses/NotFound"447 summary: Epoch Information448 description: Get the epoch information, all epochs if no epoch specified449 operationId: epoch_info450 /epoch_params:451 get:452 tags:453 - Epoch454 parameters:455 - in: query456 name: _epoch_no457 required: true458 schema:459 type: string460 description: Epoch number (required to get specific epoch data).461 responses:462 "200":463 description: Success!!464 content:465 application/json:466 schema:467 $ref: "#/components/schemas/epoch_params"468 "400":469 $ref: "#/components/responses/BadRequest"470 "401":471 $ref: "#/components/responses/Unauthorized"472 "404":473 $ref: "#/components/responses/NotFound"474 summary: Epoch's Protocol Parameters475 description: Get the protocol parameters for specific epoch, returns information about all epochs if no epoch specified476 operationId: epoch_params477 /epoch_block_protocols:478 get:479 tags:480 - Epoch481 parameters:482 - in: query483 name: _epoch_no484 required: true485 schema:486 type: string487 description: Epoch number (required to get specific epoch data).488 responses:489 "200":490 description: Success!!491 content:492 application/json:493 schema:494 $ref: "#/components/schemas/epoch_block_protocols"495 "400":496 $ref: "#/components/responses/BadRequest"497 "401":498 $ref: "#/components/responses/Unauthorized"499 "404":500 $ref: "#/components/responses/NotFound"501 summary: Epoch's Block Protocols502 description: Get the information about block protocol distribution in epoch503 operationId: epoch_block_protocols504 /blocks:505 get:506 tags:507 - Block508 responses:509 "200":510 description: Success!!511 content:512 application/json:513 schema:514 $ref: "#/components/schemas/blocks"515 "400":516 $ref: "#/components/responses/BadRequest"517 "401":518 $ref: "#/components/responses/Unauthorized"519 "404":520 $ref: "#/components/responses/NotFound"521 summary: Block List522 description: Get summarised details about all blocks (paginated - latest first)523 operationId: blocks524 parameters:525 - in: query526 name: epoch_no527 description: Filter blocks by epoch. Use "epoch_no=eq.{value}" to filter by an exact match. When epoch_no is not specified, the API defaults to "eq.{epoch_no}" where {epoch_no} is the latest epoch fetched from the /tip endpoint.528 required: true529 schema:530 type: string531 example: "eq.450"532 - in: query533 name: limit534 required: true535 schema:536 type: number537 default: "5"538 example: "15"539 /block_info:540 post:541 tags:542 - Block543 requestBody:544 description: Array of Cardano stake address(es) in bech32 format with optional epoch number to filter by.545 required: true546 content:547 application/json:548 schema:549 type: object550 properties:551 _block_hashes:552 type: array553 items:554 type: string555 description: Hash of the block556 responses:557 "200":558 description: Success559 content:560 application/json:561 schema:562 $ref: "#/components/schemas/block_info"563 "400":564 $ref: "#/components/responses/BadRequest"565 "401":566 $ref: "#/components/responses/Unauthorized"567 "404":568 $ref: "#/components/responses/NotFound"569 summary: Block Information570 description: Get detailed information about a specific block571 operationId: block_info572 /block_txs:573 post:574 tags:575 - Block576 requestBody:577 description: Array of Cardano stake address(es) in bech32 format with optional epoch number to filter by.578 required: true579 content:580 application/json:581 schema:582 type: object583 properties:584 _block_hashes:585 type: array586 items:587 type: string588 description: Hash of the block589 responses:590 "200":591 description: Success!!592 content:593 application/json:594 schema:595 $ref: "#/components/schemas/block_txs"596 "400":597 $ref: "#/components/responses/BadRequest"598 "401":599 $ref: "#/components/responses/Unauthorized"600 "404":601 $ref: "#/components/responses/NotFound"602 summary: Block Transactions603 description: Get a list of all transactions included in provided blocks604 operationId: block_txs605 /utxo_info:606 post:607 tags:608 - Transactions609 requestBody:610 description: Array of Cardano stake address(es) in bech32 format with optional epoch number to filter by.611 required: true612 content:613 application/json:614 schema:615 type: object616 properties:617 _utxo_refs:618 type: array619 items:620 type: string621 description: Array of Cardano utxo references in the form "hash#index"622 _extended:623 type: boolean624 default: false625 description: Controls whether or not certain optional fields supported by a given endpoint are populated 626 required:627 - _utxo_refs628 example:629 _utxo_refs:630 - "f144a8264acf4bdfe2e1241170969c930d64ab6b0996a4a45237b623f1dd670e#0"631 - "0b8ba3bed976fa4913f19adc9f6dd9063138db5b4dd29cecde369456b5155e94#0"632 _extended: false633 responses:634 "200":635 description: Success!636 content:637 application/json:638 schema:639 $ref: "#/components/schemas/utxo_infos"640 "400":641 $ref: "#/components/responses/BadRequest"642 "401":643 $ref: "#/components/responses/Unauthorized"644 "404":645 $ref: "#/components/responses/NotFound"646 summary: UTxO Info647 description: Get UTxO set for requested UTxO references648 operationId: utxo_info649 /tx_info:650 post:651 tags:652 - Transactions653 requestBody:654 description: Array of Cardano stake address(es) in bech32 format with optional epoch number to filter by.655 required: true656 content:657 application/json:658 schema:659 type: object660 properties:661 _tx_hashes:662 type: array663 items:664 type: string665 description: Array of Cardano Transaction hashes666 responses:667 "200":668 description: Success!!669 content:670 application/json:671 schema:672 $ref: "#/components/schemas/tx_info"673 "400":674 $ref: "#/components/responses/BadRequest"675 "401":676 $ref: "#/components/responses/Unauthorized"677 "404":678 $ref: "#/components/responses/NotFound"679 summary: Transaction Information680 description: Get detailed information about transaction(s)681 operationId: tx_info682 /tx_metadata:683 post:684 tags:685 - Transactions686 requestBody:687 $ref: "#/components/requestBodies/tx_ids"688 responses:689 "200":690 description: Success!!691 content:692 application/json:693 schema:694 $ref: "#/components/schemas/tx_metadata"695 "400":696 $ref: "#/components/responses/BadRequest"697 "401":698 $ref: "#/components/responses/Unauthorized"699 "404":700 $ref: "#/components/responses/NotFound"701 summary: Transaction Metadata702 description: Get metadata information (if any) for given transaction(s)703 operationId: tx_metadata704 parameters:705 - in: query706 name: _tx_hashes707 required: true708 schema:709 type: string710 example: ["e2741f3ee7d3d033be03eabe2c74a181a2ee765c08a32b6a6e8a2d39ca451505"]711 /tx_metalabels:712 get:713 tags:714 - Transactions715 responses:716 "200":717 description: Success!!718 content:719 application/json:720 schema:721 $ref: "#/components/schemas/tx_metalabels"722 "400":723 $ref: "#/components/responses/BadRequest"724 "401":725 $ref: "#/components/responses/Unauthorized"726 "404":727 $ref: "#/components/responses/NotFound"728 summary: Transaction Metadata Labels729 description: Get a list of all transaction metalabels730 operationId: tx_metalabels731 post:732 tags:733 - Transactions734 requestBody:735 $ref: "#/components/requestBodies/txbin"736 x-code-samples:737 - lang: Shell738 source: >739 # Assuming ${data} is a raw binary serialized transaction on the file-system.740 741 # If using a CLI-generated tx file, please ensure to deserialise (using `xxd -p -r <<< $(jq .cborHex ${tx.signed}) > ${data}`) first before submitting.742 743 curl -X POST \744 --header "Content-Type: application/cbor" \745 --data-binary @${data} https://api.koios.rest/api/v1/submittx746 responses:747 "202":748 description: OK749 content:750 application/json:751 schema:752 description: The transaction id.753 type: string754 format: hex755 minLength: 64756 maxLength: 64757 example: 92bcd06b25dfbd89b578d536b4d3b7dd269b7c2aa206ed518012cffe0444d67f758 "400":759 description: An error occured while submitting transaction.760 summary: Submit Transaction761 description: Submit an already serialized transaction to the network.762 operationId: submittx763 /tx_status:764 post:765 tags:766 - Transactions767 requestBody:768 $ref: "#/components/requestBodies/tx_ids"769 responses:770 "200":771 description: Success!!772 content:773 application/json:774 schema:775 $ref: "#/components/schemas/tx_status"776 "400":777 $ref: "#/components/responses/BadRequest"778 "401":779 $ref: "#/components/responses/Unauthorized"780 "404":781 $ref: "#/components/responses/NotFound"782 summary: Transaction Status783 description: Get the number of block confirmations for a given transaction hash list784 operationId: tx_status785 parameters:786 - in: query787 name: _tx_hashes788 required: true789 schema:790 type: string791 example: ["e2741f3ee7d3d033be03eabe2c74a181a2ee765c08a32b6a6e8a2d39ca451505"]792 /tx_utxos:793 post:794 tags:795 - Transactions796 deprecated: true797 requestBody:798 $ref: "#/components/requestBodies/tx_ids"799 responses:800 "200":801 description: Success!!802 content:803 application/json:804 schema:805 $ref: "#/components/schemas/tx_utxos"806 "400":807 $ref: "#/components/responses/BadRequest"808 "401":809 $ref: "#/components/responses/Unauthorized"810 "404":811 $ref: "#/components/responses/NotFound"812 summary: Transaction UTxOs813 description: Get UTxO set (inputs/outputs) of transactions [DEPRECATED - Use /utxo_info instead].814 operationId: tx_utxos815 parameters:816 - in: query817 name: _tx_hashes818 required: true819 schema:820 type: string821 example: ["e2741f3ee7d3d033be03eabe2c74a181a2ee765c08a32b6a6e8a2d39ca451505"]822 /address_info:823 post:824 tags:825 - Address826 requestBody:827 $ref: "#/components/requestBodies/payment_addresses"828 responses:829 "200":830 description: Success!!831 content:832 application/json:833 schema:834 $ref: "#/components/schemas/address_info"835 "400":836 $ref: "#/components/responses/BadRequest"837 "401":838 $ref: "#/components/responses/Unauthorized"839 "404":840 $ref: "#/components/responses/NotFound"841 summary: Address Information842 description: Get address info - balance, associated stake address (if any) and UTxO set for given addresses843 operationId: address_info844 parameters:845 - in: query846 name: _addresses847 required: true848 schema:849 type: string850 example: ["addr1qy2jt0qpqz2z2z9zx5w4xemekkce7yderz53kjue53lpqv90lkfa9sgrfjuz6uvt4uqtrqhl2kj0a9lnr9ndzutx32gqleeckv"]851 /address_assets:852 post:853 tags:854 - Address855 requestBody:856 $ref: "#/components/requestBodies/payment_addresses"857 responses:858 "200":859 description: Success!!860 content:861 application/json:862 schema:863 $ref: "#/components/schemas/address_assets"864 "400":865 $ref: "#/components/responses/BadRequest"866 "401":867 $ref: "#/components/responses/Unauthorized"868 "404":869 $ref: "#/components/responses/NotFound"870 summary: Address Assets871 description: Get the list of all the assets (policy, name and quantity) for given addresses872 operationId: address_assets873 parameters:874 - in: query875 name: _addresses876 required: true877 schema:878 type: string879 example: ["addr1qy2jt0qpqz2z2z9zx5w4xemekkce7yderz53kjue53lpqv90lkfa9sgrfjuz6uvt4uqtrqhl2kj0a9lnr9ndzutx32gqleeckv"]880 /account_list:881 get:882 tags:883 - Stake Account884 responses:885 "200":886 description: Success!!887 content:888 application/json:889 schema:890 $ref: "#/components/schemas/account_list"891 "400":892 $ref: "#/components/responses/BadRequest"893 "401":894 $ref: "#/components/responses/Unauthorized"895 "404":896 $ref: "#/components/responses/NotFound"897 summary: Account List898 description: Get a list of all stake addresses that have atleast 1 transaction899 operationId: account_list900 /account_info:901 post:902 tags:903 - Stake Account904 requestBody:905 description: Array of Cardano stake credential(s) in bech32 format906 required: true907 content:908 application/json:909 schema:910 required:911 - _stake_addresses912 type: object913 properties:914 _stake_addresses:915 format: text916 type: array917 items:918 type: string919 description: Array of Cardano stake address(es) in bech32 format920 example:921 _stake_addresses:922 - stake1uyrx65wjqjgeeksd8hptmcgl5jfyrqkfq0xe8xlp367kphsckq250923 - stake1uxpdrerp9wrxunfh6ukyv5267j70fzxgw0fr3z8zeac5vyqhf9jhy924 responses:925 "200":926 description: Success!!927 content:928 application/json:929 schema:930 $ref: "#/components/schemas/account_info"931 "400":932 $ref: "#/components/responses/BadRequest"933 "401":934 $ref: "#/components/responses/Unauthorized"935 "404":936 $ref: "#/components/responses/NotFound"937 summary: Account Information938 description: Get the account information for given stake addresses939 operationId: account_info940 /account_txs:941 get:942 tags:943 - Stake Account944 summary: Account Txs945 description: Get a list of all Txs for a given stake address (account)946 operationId: account_txs947 parameters:948 - in: query949 name: _stake_address950 description: Cardano staking address (reward account) in bech32 format for which the transactions are requested.951 required: true952 schema:953 type: string954 example: stake1u8yxtugdv63wxafy9d00nuz6hjyyp4qnggvc9a3vxh8yl0ckml2uz955 - in: query956 name: _after_block_height957 description: Block height for specifying time delta958 required: true959 allowEmptyValue: true960 schema:961 type: number962 default: 1000000963 example: 100000964 responses:965 '200':966 description: Success!!967 content:968 application/json:969 schema:970 $ref: '#/components/schemas/address_txs'971 '400':972 $ref: '#/components/responses/BadRequest'973 '401':974 $ref: '#/components/responses/Unauthorized'975 '404':976 $ref: '#/components/responses/NotFound'977 /account_rewards:978 post:979 tags:980 - Stake Account981 requestBody:982 description: Array of Cardano stake address(es) in bech32 format with optional epoch number to filter by.983 required: true984 content:985 application/json:986 schema:987 type: object988 properties:989 _stake_addresses:990 type: array991 items:992 type: string993 description: Array of Cardano stake address(es) in bech32 format.994 _epoch_no:995 type: integer996 description: Only fetch information for a specific epoch.997 required:998 - _stake_addresses999 example:1000 _stake_addresses:1001 - stake1uyrx65wjqjgeeksd8hptmcgl5jfyrqkfq0xe8xlp367kphsckq2501002 - stake1uxpdrerp9wrxunfh6ukyv5267j70fzxgw0fr3z8zeac5vyqhf9jhy1003 _epoch_no: 4091004 "200":1005 description: Success!!1006 content:1007 application/json:1008 schema:1009 $ref: "#/components/schemas/account_rewards"1010 "400":1011 $ref: "#/components/responses/BadRequest"1012 "401":1013 $ref: "#/components/responses/Unauthorized"1014 "404":1015 $ref: "#/components/responses/NotFound"1016 summary: Account Rewards1017 description: Get the full rewards history (including MIR) for given stake addresses1018 operationId: account_rewards1019 /account_updates:1020 post:1021 tags:1022 - Stake Account1023 requestBody:1024 $ref: "#/components/requestBodies/stake_addresses"1025 responses:1026 "200":1027 description: Success!!1028 content:1029 application/json:1030 schema:1031 $ref: "#/components/schemas/account_updates"1032 "400":1033 $ref: "#/components/responses/BadRequest"1034 "401":1035 $ref: "#/components/responses/Unauthorized"1036 "404":1037 $ref: "#/components/responses/NotFound"1038 summary: Account Updates1039 description: Get the account updates (registration, deregistration, delegation and withdrawals) for given stake addresses1040 operationId: account_updates1041 /account_assets:1042 post:1043 tags:1044 - Stake Account1045 requestBody:1046 $ref: "#/components/requestBodies/stake_addresses"1047 responses:1048 "200":1049 description: Success!!1050 content:1051 application/json:1052 schema:1053 $ref: "#/components/schemas/account_assets"1054 "400":1055 $ref: "#/components/responses/BadRequest"1056 "401":1057 $ref: "#/components/responses/Unauthorized"1058 "404":1059 $ref: "#/components/responses/NotFound"1060 summary: Account Assets1061 description: Get the native asset balance for a given stake address1062 operationId: account_assets1063 parameters:1064 - in: query1065 name: _stake_address1066 description: Cardano staking address (reward account) in bech32 format for which the transactions are requested.1067 required: true1068 schema:1069 type: string1070 example: stake1u8yxtugdv63wxafy9d00nuz6hjyyp4qnggvc9a3vxh8yl0ckml2uz1071 /asset_list:1072 get:1073 tags:1074 - Asset1075 responses:1076 "200":1077 description: Success!!1078 content:1079 application/json:1080 schema:1081 $ref: "#/components/schemas/asset_list"1082 "400":1083 $ref: "#/components/responses/BadRequest"1084 "401":1085 $ref: "#/components/responses/Unauthorized"1086 "404":1087 $ref: "#/components/responses/NotFound"1088 summary: Asset List1089 description: Get the list of all native assets (paginated)1090 operationId: asset_list1091components:1092 securitySchemes:1093 bearerAuth: # This is an arbitrary name for the security scheme1094 type: http1095 scheme: bearer1096 bearerFormat: JWT # Optional, can be omitted if not using JWT bearer tokens1097 parameters:1098 _after_block_height:1099 deprecated: false1100 name: _after_block_height1101 description: Block height for specifying time delta1102 schema:1103 type: number1104 example: 500001105 in: query1106 required: false1107 allowEmptyValue: true1108 _epoch_no:1109 deprecated: false1110 name: _epoch_no1111 description: Epoch Number to fetch details for1112 in: query1113 required: true1114 schema:1115 type: integer1116 format: int321117 description: The epoch number to retrieve data for.1118 example: "320"1119 _stake_address:1120 deprecated: false1121 name: _stake_address1122 description: Cardano staking address (reward account) in bech32 format for which the transactions are requested.1123 schema:1124 type: string1125 example: stake1u8yxtugdv63wxafy9d00nuz6hjyyp4qnggvc9a3vxh8yl0ckml2uz1126 in: query1127 required: true1128 allowEmptyValue: false1129 _asset_policy:1130 deprecated: false1131 name: _asset_policy1132 description: Asset Policy ID in hexadecimal format (hex)1133 schema:1134 type: string1135 example: 750900e4999ebe0d58f19b634768ba25e525aaf12403bfe8fe1305011136 in: query1137 required: true1138 allowEmptyValue: false1139 _asset_name:1140 deprecated: false1141 name: _asset_name1142 description: Asset Name in hexadecimal format (hex), empty asset name returns royalties1143 schema:1144 type: string1145 example: 424f4f4b1146 in: query1147 required: false1148 allowEmptyValue: true1149 _asset_policy_nft:1150 deprecated: false1151 name: _asset_policy1152 description: NFT Policy ID in hexadecimal format (hex)1153 schema:1154 type: string1155 example: f0ff48bbb7bbe9d59a40f1ce90e9e9d0ff5002ec48f232b49ca0fb9a1156 in: query1157 required: true1158 allowEmptyValue: false1159 _asset_name_nft:1160 deprecated: false1161 name: _asset_name1162 description: NFT Name in hexadecimal format (hex)1163 schema:1164 type: string1165 example: 68616e646c651166 in: query1167 required: false1168 allowEmptyValue: true1169 _extended:1170 deprecated: false1171 name: _extended1172 description: Controls whether or not certain optional fields supported by a given endpoint are populated as a part of the call1173 schema:1174 type: boolean1175 example: false1176 in: query1177 required: false1178 allowEmptyValue: true1179 _history:1180 deprecated: false1181 name: _history1182 description: Include all historical transactions, setting to false includes only the non-empty ones1183 schema:1184 type: boolean1185 example: false1186 in: query1187 required: false1188 allowEmptyValue: false1189 _include_next_epoch:1190 deprecated: false1191 name: _include_next_epoch1192 description: Include information about nearing but not yet started epoch, to get access to active stake snapshot1193 information if available1194 schema:1195 type: boolean1196 example: false1197 in: query1198 required: false1199 allowEmptyValue: true1200 _pool_bech32: