openapi: 3.0.3
info:
  version: 0.1.89
  title: Blockfrost.io ~ API Documentation Cardano » Accounts Cardano » Scripts API
  x-logo:
    url: https://staging.blockfrost.io/images/logo.svg
    altText: Blockfrost
  contact:
    name: Blockfrost Team
    url: https://blockfrost.io
    email: contact@blockfrost.io
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  termsOfService: https://blockfrost.io/terms
  description: "Blockfrost is an API as a service that allows users to interact with the Cardano blockchain, Midnight blockchain, and parts of their ecosystems.\n\n## Tokens\n\nAfter signing up on https://blockfrost.io, a `project_id` token is automatically generated for each project.\nHTTP header of your request MUST include this `project_id` in order to authenticate against Blockfrost servers.\n\n## Available networks\n\nAt the moment, you can use the following networks. Please, note that each network has its own `project_id`.\n\n<table>\n  <tbody>\n    <tr>\n      <td>\n          <b>Network</b>\n      </td>\n      <td>\n          <b>Endpoint</b>\n      </td>\n    </tr>\n    <tr>\n        <td>Cardano mainnet</td>\n        <td>\n            <code>https://cardano-mainnet.blockfrost.io/api/v0</code>\n        </td>\n    </tr>\n    <tr>\n        <td>Cardano preprod</td>\n        <td>\n            <code>https://cardano-preprod.blockfrost.io/api/v0</code>\n        </td>\n    </tr>\n    <tr>\n        <td>Cardano preview</td>\n        <td>\n            <code>https://cardano-preview.blockfrost.io/api/v0</code>\n        </td>\n    </tr>\n    <tr>\n        <td>Midnight mainnet</td>\n        <td>\n            <code>https://midnight-mainnet.blockfrost.io/api/v0</code>\n        </td>\n    </tr>\n    <tr>\n        <td>InterPlanetary File System</td>\n        <td>\n            <code>https://ipfs.blockfrost.io/api/v0</code>\n        </td>\n    </tr>\n  </tbody>\n</table>\n\n## Concepts\n\n* All endpoints return either a JSON object or an array.\n* Data is returned in *ascending* (oldest first, newest last) order, if not stated otherwise.\n  * You might use the `?order=desc` query parameter to reverse this order.\n* By default, we return 100 results at a time. You have to use `?page=2` to list through the results.\n* All time and timestamp related fields (except `server_time`) are in seconds of UNIX time.\n* All amounts are returned in Lovelaces, where 1 ADA = 1 000 000 Lovelaces.\n* Addresses, accounts and pool IDs are in Bech32 format.\n* All values are case sensitive.\n* All hex encoded values are lower case.\n* Examples are not based on real data. Any resemblance to actual events is purely coincidental.\n* We allow to upload files up to 100MB of size to IPFS. This might increase in the future.\n* Only pinned IPFS files are counted towards the IPFS quota.\n* Non-pinned IPFS files are subject to regular garbage collection and will be removed unless pinned.\n* We allow maximum of 100 queued pins per IPFS user.\n\n## Errors\n\n### HTTP Status codes\n\nThe following are HTTP status code your application might receive when reaching Blockfrost endpoints and\nit should handle all of these cases.\n\n* HTTP `400` return code is used when the request is not valid.\n* HTTP `402` return code is used when the projects exceed their daily request limit.\n* HTTP `403` return code is used when the request is not authenticated.\n* HTTP `404` return code is used when the resource doesn't exist.\n* HTTP `418` return code is used when the user has been auto-banned for flooding too much after previously receiving error code `402` or `429`.\n* HTTP `425` return code is used in Cardano networks, when the user has submitted a transaction when the mempool is already full, not accepting new txs straight away.\n* HTTP `425` return code is used in IPFS network, when the user has submitted a pin when the pin queue is already full, not accepting new pins straight away.\n* HTTP `429` return code is used when the user has sent too many requests in a given amount of time and therefore has been rate-limited.\n* HTTP `500` return code is used when our endpoints are having a problem.\n\n### Error codes\n\nAn internal error code number is used for better indication of the error in question. It is passed using the following payload.\n\n```json\n{\n  \"status_code\": 403,\n  \"error\": \"Forbidden\",\n  \"message\": \"Invalid project token.\"\n}\n```\n## Limits\n\nThere are two types of limits we are enforcing:\n\nThe first depends on your plan and is the number of request we allow per day. We defined the day from midnight to midnight of UTC time.\n\nThe second is rate limiting. We limit an end user, distinguished by IP address, to 10 requests per second. On top of that, we allow\neach user to send burst of 500 requests, which cools off at rate of 10 requests per second. In essence, a user is allowed to make another\nwhole burst after (currently) 500/10 = 50 seconds. E.g. if a user attempts to make a call 3 seconds after whole burst, 30 requests will be processed.\nWe believe this should be sufficient for most of the use cases. If it is not and you have a specific use case, please get in touch with us, and\nwe will make sure to take it into account as much as we can.\n\n## SDKs\n\nWe support a number of SDKs that will help you in developing your application on top of Blockfrost.\n\n<table>\n  <tbody>\n    <tr>\n        <td><b>Programming language</b></td>\n        <td><b>SDK</b></td>\n    </tr>\n    <tr>\n        <td>JavaScript</td>\n        <td>\n            <a href=\"https://github.com/blockfrost/blockfrost-js\">blockfrost-js</a>\n        </td>\n    </tr>\n    <tr>\n        <td>Haskell</td>\n        <td>\n            <a href=\"https://github.com/blockfrost/blockfrost-haskell\">blockfrost-haskell</a>\n        </td>\n    </tr>\n    <tr>\n        <td>Python</td>\n        <td>\n            <a href=\"https://github.com/blockfrost/blockfrost-python\">blockfrost-python</a>\n        </td>\n    </tr>\n    <tr>\n        <td>Rust</td>\n        <td>\n            <a href=\"https://github.com/blockfrost/blockfrost-rust\">blockfrost-rust</a>\n        </td>\n    </tr>\n    <tr>\n        <td>Golang</td>\n        <td>\n            <a href=\"https://github.com/blockfrost/blockfrost-go\">blockfrost-go</a>\n        </td>\n    </tr>\n    <tr>\n        <td>Ruby</td>\n        <td>\n            <a href=\"https://github.com/blockfrost/blockfrost-ruby\">blockfrost-ruby</a>\n        </td>\n    </tr>\n    <tr>\n        <td>Java</td>\n        <td>\n            <a href=\"https://github.com/blockfrost/blockfrost-java\">blockfrost-java</a>\n        </td>\n    </tr>\n    <tr>\n        <td>Scala</td>\n        <td>\n            <a href=\"https://github.com/blockfrost/blockfrost-scala\">blockfrost-scala</a>\n        </td>\n    </tr>\n    <tr>\n        <td>Swift</td>\n        <td>\n            <a href=\"https://github.com/blockfrost/blockfrost-swift\">blockfrost-swift</a>\n        </td>\n    </tr>\n    <tr>\n        <td>Kotlin</td>\n        <td>\n            <a href=\"https://github.com/blockfrost/blockfrost-kotlin\">blockfrost-kotlin</a>\n        </td>\n    </tr>\n    <tr>\n        <td>Elixir</td>\n        <td>\n            <a href=\"https://github.com/blockfrost/blockfrost-elixir\">blockfrost-elixir</a>\n        </td>\n    </tr>\n    <tr>\n        <td>.NET</td>\n        <td>\n            <a href=\"https://github.com/blockfrost/blockfrost-dotnet\">blockfrost-dotnet</a>\n        </td>\n    </tr>\n    <tr>\n        <td>Arduino</td>\n        <td>\n            <a href=\"https://github.com/blockfrost/blockfrost-arduino\">blockfrost-arduino</a>\n        </td>\n    </tr>\n    <tr>\n        <td>PHP</td>\n        <td>\n            <a href=\"https://github.com/blockfrost/blockfrost-php\">blockfrost-php</a>\n        </td>\n    </tr>\n    <tr>\n        <td>Crystal</td>\n        <td>\n            <a href=\"https://github.com/blockfrost/blockfrost-crystal\">blockfrost-crystal</a>\n        </td>\n    </tr>\n  </tbody>\n</table>\n\n\n## Midnight API\n\n\nThe Midnight Indexer API exposes a GraphQL API that enables clients to query and subscribe to blockchain data — blocks, transactions, contracts, and wallet-related events — indexed from the Midnight blockchain.\n\nAvailable networks: `mainnet`, `preprod`, `preview`\n\n| Service | URL | Protocol |\n|---------|-----|----------|\n| **Indexer HTTP API** | `https://midnight-{network}.blockfrost.io/api/v0` | HTTP POST (GraphQL) |\n| **Indexer Subscriptions API** | `wss://midnight-{network}.blockfrost.io/api/v0/ws` | WebSocket |\n| **Node RPC** | `https://rpc.midnight-{network}.blockfrost.io` | JSON-RPC |\n\n\nFor the full documentation — queries, mutations, subscriptions, authentication options, and examples — see the Midnight GraphQL API Reference:\n\n[![Explore the Midnight API →](https://img.shields.io/badge/Explore_the_Midnight_API_→-0033AD?style=for-the-badge)](./midnight/)\n"
servers:
- url: https://cardano-mainnet.blockfrost.io/api/v0
  description: Cardano Mainnet network
- url: https://cardano-preprod.blockfrost.io/api/v0
  description: Cardano Preprod network
- url: https://cardano-preview.blockfrost.io/api/v0
  description: Cardano Preview network
- url: https://localhost:3000
  description: local
security:
- project_id: []
tags:
- name: Cardano » Scripts
paths:
  /scripts:
    get:
      tags:
      - Cardano » Scripts
      summary: Scripts
      description: List of scripts.
      parameters:
      - in: query
        name: count
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 100
        description: The number of results displayed on one page.
      - in: query
        name: page
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 21474836
          default: 1
        description: The page number for listing the results.
      - in: query
        name: order
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
          default: asc
        description: 'The ordering of items from the point of view of the blockchain,

          not the page listing itself. By default, we return oldest first, newest last.

          '
      responses:
        '200':
          description: Return list of scripts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/scripts'
        '400':
          $ref: '#/components/responses/400'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '418':
          $ref: '#/components/responses/418'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /scripts/{script_hash}:
    get:
      tags:
      - Cardano » Scripts
      summary: Specific script
      description: Information about a specific script
      parameters:
      - in: path
        name: script_hash
        required: true
        schema:
          type: string
        description: Hash of the script
        example: e1457a0c47dfb7a2f6b8fbb059bdceab163c05d34f195b87b9f2b30e
      responses:
        '200':
          description: Return the information about a specific script
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/script'
        '400':
          $ref: '#/components/responses/400'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '418':
          $ref: '#/components/responses/418'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /scripts/{script_hash}/json:
    get:
      tags:
      - Cardano » Scripts
      summary: Script JSON
      description: JSON representation of a `timelock` script
      parameters:
      - in: path
        name: script_hash
        required: true
        schema:
          type: string
        description: Hash of the script
        example: e1457a0c47dfb7a2f6b8fbb059bdceab163c05d34f195b87b9f2b30e
      responses:
        '200':
          description: Return the JSON representation of a `timelock` script
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/script_json'
        '400':
          $ref: '#/components/responses/400'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '418':
          $ref: '#/components/responses/418'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /scripts/{script_hash}/cbor:
    get:
      tags:
      - Cardano » Scripts
      summary: Script CBOR
      description: CBOR representation of a `plutus` script
      parameters:
      - in: path
        name: script_hash
        required: true
        schema:
          type: string
        description: Hash of the script
        example: e1457a0c47dfb7a2f6b8fbb059bdceab163c05d34f195b87b9f2b30e
      responses:
        '200':
          description: Return the CBOR representation of a `plutus` script
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/script_cbor'
        '400':
          $ref: '#/components/responses/400'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '418':
          $ref: '#/components/responses/418'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /scripts/{script_hash}/redeemers:
    get:
      tags:
      - Cardano » Scripts
      summary: Redeemers of a specific script
      description: List of redeemers of a specific script
      parameters:
      - in: path
        name: script_hash
        required: true
        schema:
          type: string
        description: Hash of the script
        example: e1457a0c47dfb7a2f6b8fbb059bdceab163c05d34f195b87b9f2b30e
      - in: query
        name: count
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 100
        description: The number of results displayed on one page.
      - in: query
        name: page
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 21474836
          default: 1
        description: The page number for listing the results.
      - in: query
        name: order
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
          default: asc
        description: 'The ordering of items from the point of view of the blockchain,

          not the page listing itself. By default, we return oldest first, newest last.

          '
      responses:
        '200':
          description: Return the information about redeemers of a specific script
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/script_redeemers'
        '400':
          $ref: '#/components/responses/400'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '418':
          $ref: '#/components/responses/418'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /scripts/datum/{datum_hash}:
    get:
      tags:
      - Cardano » Scripts
      summary: Datum value
      description: Query JSON value of a datum by its hash
      parameters:
      - in: path
        name: datum_hash
        required: true
        schema:
          type: string
        description: Hash of the datum
        example: db583ad85881a96c73fbb26ab9e24d1120bb38f45385664bb9c797a2ea8d9a2d
      responses:
        '200':
          description: Return the datum value
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/script_datum'
        '400':
          $ref: '#/components/responses/400'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '418':
          $ref: '#/components/responses/418'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /scripts/datum/{datum_hash}/cbor:
    get:
      tags:
      - Cardano » Scripts
      summary: Datum CBOR value
      description: Query CBOR serialised datum by its hash
      parameters:
      - in: path
        name: datum_hash
        required: true
        schema:
          type: string
        description: Hash of the datum
        example: db583ad85881a96c73fbb26ab9e24d1120bb38f45385664bb9c797a2ea8d9a2d
      responses:
        '200':
          description: Return the CBOR serialised datum value
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/script_datum_cbor'
        '400':
          $ref: '#/components/responses/400'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '418':
          $ref: '#/components/responses/418'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
components:
  responses:
    '500':
      description: Internal Server Error
      content:
        application/json:
          schema:
            type: object
            properties:
              status_code:
                type: integer
                example: 500
              error:
                type: string
                example: Internal Server Error
              message:
                type: string
                example: An unexpected response was received from the backend.
            required:
            - error
            - message
            - status_code
    '429':
      description: Usage limit reached
      content:
        application/json:
          schema:
            type: object
            properties:
              status_code:
                type: integer
                example: 429
              error:
                type: string
                example: Project Over Limit
              message:
                type: string
                example: Usage is over limit.
            required:
            - error
            - message
            - status_code
    '403':
      description: Authentication secret is missing or invalid
      content:
        application/json:
          schema:
            type: object
            properties:
              status_code:
                type: integer
                example: 403
              error:
                type: string
                example: Forbidden
              message:
                type: string
                example: Invalid project token.
            required:
            - error
            - message
            - status_code
    '404':
      description: Component not found
      content:
        application/json:
          schema:
            type: object
            properties:
              status_code:
                type: integer
                example: 404
              error:
                type: string
                example: Not Found
              message:
                type: string
                example: The requested component has not been found.
            required:
            - error
            - message
            - status_code
    '400':
      description: Bad request
      content:
        application/json:
          schema:
            type: object
            properties:
              status_code:
                type: integer
                example: 400
              error:
                type: string
                example: Bad Request
              message:
                type: string
                example: Backend did not understand your request.
            required:
            - error
            - message
            - status_code
    '418':
      description: IP has been auto-banned for extensive sending of requests after usage limit has been reached
      content:
        application/json:
          schema:
            type: object
            properties:
              status_code:
                type: integer
                example: 418
              error:
                type: string
                example: Requested Banned
              message:
                type: string
                example: IP has been auto-banned for flooding.
            required:
            - error
            - message
            - status_code
  schemas:
    script:
      type: object
      properties:
        script_hash:
          type: string
          example: 13a3efd825703a352a8f71f4e2758d08c28c564e8dfcce9f77776ad1
          description: Script hash
        type:
          type: string
          enum:
          - timelock
          - plutusV1
          - plutusV2
          - plutusV3
          example: plutusV1
          description: Type of the script language
        serialised_size:
          type: integer
          nullable: true
          description: The size of the CBOR serialised script, if a Plutus script
          example: 3119
      required:
      - script_hash
      - type
      - serialised_size
    script_datum_cbor:
      type: object
      properties:
        cbor:
          type: string
          description: CBOR serialized datum
      required:
      - cbor
      example:
        cbor: 19a6aa
    script_json:
      type: object
      properties:
        json:
          anyOf:
          - type: string
          - type: object
            additionalProperties: true
          - type: array
            items: {}
          - type: integer
          - type: number
          - type: boolean
          - type: 'null'
          description: JSON contents of the `timelock` script, null for `plutus` scripts
      required:
      - json
      example:
        json:
          type: atLeast
          scripts:
          - type: sig
            keyHash: 654891a4db2ea44b5263f4079a33efa0358ba90769e3d8f86a4a0f81
          - type: sig
            keyHash: 8685ad48f9bebb8fdb6447abbe140645e0bf743ff98da62e63e2147f
          - type: sig
            keyHash: cb0f3b3f91693374ff7ce1d473cf6e721c7bab52b0737f04164e5a2d
          required: 2
    script_datum:
      type: object
      properties:
        json_value:
          type: object
          additionalProperties: true
          description: JSON content of the datum
      required:
      - json_value
      example:
        json_value:
          int: 42
    script_redeemers:
      type: array
      items:
        type: object
        properties:
          tx_hash:
            type: string
            example: 1a0570af966fb355a7160e4f82d5a80b8681b7955f5d44bec0dce628516157f0
            description: Hash of the transaction
          tx_index:
            type: integer
            example: 0
            description: The index of the redeemer pointer in the transaction
          purpose:
            type: string
            enum:
            - spend
            - mint
            - cert
            - reward
            example: spend
            description: Validation purpose
          redeemer_data_hash:
            type: string
            example: 923918e403bf43c34b4ef6b48eb2ee04babed17320d8d1b9ff9ad086e86f44ec
            description: Datum hash of the redeemer
          datum_hash:
            type: string
            example: 923918e403bf43c34b4ef6b48eb2ee04babed17320d8d1b9ff9ad086e86f44ec
            description: Datum hash
            deprecated: true
          unit_mem:
            type: string
            example: '1700'
            description: The budget in Memory to run a script
          unit_steps:
            type: string
            example: '476468'
            description: The budget in CPU steps to run a script
          fee:
            type: string
            example: '172033'
            description: The fee consumed to run the script
        required:
        - tx_hash
        - tx_index
        - purpose
        - redeemer_data_hash
        - datum_hash
        - unit_mem
        - unit_steps
        - fee
    script_cbor:
      type: object
      properties:
        cbor:
          type: string
          nullable: true
          description: CBOR contents of the `plutus` script, null for `timelocks`
      required:
      - cbor
      example:
        cbor: 4e4d01000033222220051200120011
    scripts:
      type: array
      items:
        type: object
        properties:
          script_hash:
            type: string
            description: Script hash
        required:
        - script_hash
      example:
      - script_hash: 13a3efd825703a352a8f71f4e2758d08c28c564e8dfcce9f77776ad1
      - script_hash: e1457a0c47dfb7a2f6b8fbb059bdceab163c05d34f195b87b9f2b30e
      - script_hash: a6e63c0ff05c96943d1cc30bf53112ffff0f34b45986021ca058ec54
  securitySchemes:
    project_id:
      type: apiKey
      in: header
      name: project_id
      description: 'There are multiple token types available based on network you choose

        when creating a Blockfrost a project, for a list of token types

        see available networks.

        '