Tezos Rights API

openapi: 3.0.0
info:
  title: TzKT Accounts Rights API
  description: "# Introduction\r\n\r\nTzKT is the most widely used tool in Tezos that provides you with convenient and flexible access to the Tezos blockchain data, processed and indexed by its own indexer. \r\nYou can fetch all historical data via REST API, or subscribe for real-time data via WebSocket API. TzKT was built by the joint efforts of the entire Tezos community \r\nto help developers build more services and dapps on top of Tezos.\r\n\r\nTzKT Indexer and API are [open-source](https://github.com/baking-bad/tzkt), so don't be afraid to depend on the third-party service,\r\nbecause you can always clone, build and run it yourself to have full control over all the components.\r\n\r\nFeel free to contact us if you have any questions or feature requests.\r\nYour feedback is much appreciated!\r\n\r\n- Discord: https://discord.gg/aG8XKuwsQd\r\n- Telegram: https://t.me/baking_bad_chat\r\n- X: https://x.com/TezosBakingBad\r\n- Email: hello@bakingbad.dev\r\n\r\nAnd don't forget to star TzKT [on GitHub](https://github.com/baking-bad/tzkt) if you like it \U0001F60A\r\n\r\n# Get Started\r\n\r\nThere are two API services provided for public use:\r\n- **Free TzKT API** with free anonymous access;\r\n- **TzKT Pro** with paid subscriptions with increased rate limits, off-chain data, extended support and business-level SLA.\r\n\r\nYou can find more details about differences between available tiers [here](https://tzkt.io/api).\r\n\r\n## Free TzKT API\r\n\r\nFree-tier TzKT API is the best way to get started and explore available Tezos data and API functionality.\r\nIt doesn't require authorization and is free for everyone and for both commercial and non-commercial use.\r\n\r\n> #### Note: attribution required\r\nIf you use free-tier TzKT API, you **must** mention it on your website or application by placing the label\r\n\"Powered by TzKT API\", or \"Built with TzKT API\", or \"Data provided by TzKT API\" with a direct link to [tzkt.io](https://tzkt.io).\r\n\r\nIt's available for the following Tezos networks with the following base URLs:\r\n\r\n- Mainnet: `https://api.tzkt.io/` or `https://api.mainnet.tzkt.io/` ([view docs](https://api.tzkt.io))\r\n- Ghostnet: `https://api.ghostnet.tzkt.io/` ([view docs](https://api.ghostnet.tzkt.io))\r\n- Shadownet: `https://api.shadownet.tzkt.io/` ([view docs](https://api.shadownet.tzkt.io))\r\n- Seoulnet: `https://api.seoulnet.tzkt.io/` ([view docs](https://api.seoulnet.tzkt.io))\r\n- Tallinnnet: `https://api.tallinnnet.tzkt.io/` ([view docs](https://api.tallinnnet.tzkt.io))\r\n\r\n### Sending Requests\r\n\r\nTo send a request to Free TzKT API you need literally nothing. Just take the base URL of the particular network\r\n(for example, Tezos mainnet: `https://api.tzkt.io`) and append the path of the particular endpoint\r\n(for example, chain's head: `/v1/head`), that's pretty much it: \r\n\r\n```bash\r\ncurl https://api.tzkt.io/v1/head\r\n```\r\n\r\nRead through this documentation to explore available endpoints, query parameters\r\n(note, if you click on a query parameter, you will see available modes, such as `.eq`, `.in`, etc.)\r\nand response models. If you have any questions, do not hesitate to ask for support, Tezos community has always been very friendly! \U0001F609\r\n\r\n### Rate Limits\r\n\r\nPlease, refer to https://tzkt.io/api to check relevant rate limits.\r\n\r\nIf you exceed the limit, the API will respond with `HTTP 429` status code.\r\n\r\n## TzKT Pro\r\n\r\nTzKT Pro is intended for professional use, for those who seek for extended capabilities, performance, reliability and business-level SLA.\r\nTzKT Pro service is provided via paid subscriptions. Please, refer to [Pricing Plans](https://tzkt.io/api) to check available tiers.\r\n\r\nIt's available for the following Tezos networks with the following base URLs:\r\n\r\n- Mainnet: `https://pro.tzkt.io/` ([view docs](https://api.tzkt.io))\r\n- Testnets: *let us know if you need TzKT Pro for testnets*\r\n\r\n### Authorization\r\n\r\nTo access TzKT Pro you will need to authorize requests with your personal API key, that you will receive on your email after purchasing a subscription.\r\nThis can be done by adding the query string parameter `?apikey={your_key}` or by adding the HTTP header `apikey: {your_key}`.\r\n\r\nNote that you can have multiple API keys within a single subscription.\r\n\r\nKeep your API keys private, do not publish it anywhere and do not hardcode it, especially in public repositories.\r\nIf your key was compromised, just let us know and we will issue a new one.\r\n\r\nAlso note that passing the API key via HTTP headers is more secure, because in HTTPS headers are encrypted,\r\nbut query string is not, so the key can be unintentionally exposed to third parties.\r\n\r\n### Sending Requests\r\n\r\nSending a request with the API key passed as a query string parameter:\r\n\r\n```bash\r\ncurl https://pro.tzkt.io/v1/head?apikey={your_key}\r\n```\r\n\r\nSending a request with the API key passed via an HTTP header:\r\n\r\n```bash\r\ncurl https://pro.tzkt.io/v1/head \\\r\n    -H 'apikey: {your_key}'\r\n```\r\n\r\n### Rate Limits\r\n\r\nPlease, refer to https://tzkt.io/api to check relevant rate limits for different pricing plans.\r\n\r\nAlso, TzKT Pro provides you with the additional HTTP headers to show the allowed limits, number of available requests\r\nand the time remaining (in seconds) until the quota is reset. Here's an example:\r\n\r\n```\r\nRateLimit-Limit: 50\r\nRateLimit-Remaining: 49\r\nRateLimit-Reset: 1\r\n```\r\n\r\nIt also sends general information about your rate limits per second and per day:\r\n\r\n```\r\nX-RateLimit-Limit-Second: 50\r\nX-RateLimit-Remaining-Second: 49\r\nX-RateLimit-Limit-Day: 3000000\r\nX-RateLimit-Remaining-Day: 2994953\r\n```\r\n\r\nIf you exceed the limit, the API will respond with `HTTP 429` status code.\r\n"
  contact:
    name: Baking Bad Team
    url: https://bakingbad.dev
    email: hello@bakingbad.dev
  version: 1.17.1
  x-logo:
    url: https://tzkt.io/logo.png
    href: https://tzkt.io/
servers:
- url: https://api.tzkt.io
tags:
- name: Rights
paths:
  /v1/rights/count:
    get:
      tags:
      - Rights
      summary: Get rights count
      description: Returns the total number of stored rights.
      operationId: Rights_GetCount
      parameters:
      - name: type
        in: query
        description: Filters rights by type (`baking`, `attestation`)
        schema:
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/BakingRightTypeParameter'
        x-position: 1
        x-tzkt-extension: query-parameter
        x-tzkt-query-parameter: baking,attestation
      - name: baker
        in: query
        description: Filters rights by baker
        schema:
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/AccountParameter'
        x-position: 2
        x-tzkt-extension: query-parameter
      - name: cycle
        in: query
        description: Filters rights by cycle
        schema:
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/Int32Parameter'
        x-position: 3
        x-tzkt-extension: query-parameter
      - name: level
        in: query
        description: Filters rights by level
        schema:
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/Int32Parameter'
        x-position: 4
        x-tzkt-extension: query-parameter
      - name: slots
        in: query
        description: Filters rights by slots
        schema:
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/Int32NullParameter'
        x-position: 5
        x-tzkt-extension: query-parameter
      - name: round
        in: query
        description: Filters rights by round
        schema:
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/Int32NullParameter'
        x-position: 6
        x-tzkt-extension: query-parameter
      - name: status
        in: query
        description: Filters rights by status (`future`, `realized`, `missed`)
        schema:
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/BakingRightStatusParameter'
        x-position: 7
        x-tzkt-extension: query-parameter
        x-tzkt-query-parameter: future,realized,uncovered,missed
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: integer
                format: int32
  /v1/rights:
    get:
      tags:
      - Rights
      summary: Get rights
      description: Returns a list of rights.
      operationId: Rights_Get
      parameters:
      - name: type
        in: query
        description: Filters rights by type (`baking`, `attestation`)
        schema:
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/BakingRightTypeParameter'
        x-position: 1
        x-tzkt-extension: query-parameter
        x-tzkt-query-parameter: baking,attestation
      - name: baker
        in: query
        description: Filters rights by baker
        schema:
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/AccountParameter'
        x-position: 2
        x-tzkt-extension: query-parameter
      - name: cycle
        in: query
        description: Filters rights by cycle
        schema:
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/Int32Parameter'
        x-position: 3
        x-tzkt-extension: query-parameter
      - name: level
        in: query
        description: Filters rights by level
        schema:
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/Int32Parameter'
        x-position: 4
        x-tzkt-extension: query-parameter
      - name: slots
        in: query
        description: Filters rights by slots
        schema:
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/Int32NullParameter'
        x-position: 5
        x-tzkt-extension: query-parameter
      - name: round
        in: query
        description: Filters rights by round
        schema:
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/Int32NullParameter'
        x-position: 6
        x-tzkt-extension: query-parameter
      - name: status
        in: query
        description: Filters rights by status (`future`, `realized`, `missed`)
        schema:
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/BakingRightStatusParameter'
        x-position: 7
        x-tzkt-extension: query-parameter
        x-tzkt-query-parameter: future,realized,uncovered,missed
      - name: select
        in: query
        description: Specify comma-separated list of fields to include into response or leave it undefined to return full object. If you select single field, response will be an array of values in both `.fields` and `.values` modes.
        schema:
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/SelectParameter'
        x-position: 8
        x-tzkt-extension: query-parameter
      - name: sort
        in: query
        description: 'Sorts rights by specified field. Supported fields: `level` (default).'
        schema:
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/SortParameter'
        x-position: 9
        x-tzkt-extension: query-parameter
      - name: offset
        in: query
        description: Specifies which or how many items should be skipped
        schema:
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/OffsetParameter'
        x-position: 10
        x-tzkt-extension: query-parameter
      - name: limit
        in: query
        description: Maximum number of items to return
        schema:
          type: integer
          format: int32
          default: 100
          maximum: 10000.0
          minimum: 0.0
        x-position: 11
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BakingRight'
components:
  schemas:
    Alias:
      type: object
      additionalProperties: false
      properties:
        alias:
          type: string
          description: Account alias name (off-chain data).
          nullable: true
        address:
          type: string
          description: Account address (public key hash).
    BakingRightTypeParameter:
      type: object
      additionalProperties: false
      properties:
        eq:
          type: string
          description: '**Equal** filter mode (optional, i.e. `param.eq=123` is the same as `param=123`). \

            Specify baking right type to get items where the specified field is equal to the specified value.


            Example: `?type=baking`.'
          nullable: true
        ne:
          type: string
          description: '**Not equal** filter mode. \

            Specify baking right type to get items where the specified field is not equal to the specified value.


            Example: `?type.ne=attestation`.'
          nullable: true
      x-tzkt-extension: query-parameter
      x-tzkt-query-parameter: baking,attestation
    SortParameter:
      type: object
      additionalProperties: false
      properties:
        asc:
          type: string
          description: '**Ascending** sort mode (optional, i.e. `sort.asc=id` is the same as `sort=id`). \

            Specify a field name to sort by.


            Example: `?sort=balance`.'
          nullable: true
        desc:
          type: string
          description: '**Descending** sort mode. \

            Specify a field name to sort by descending.


            Example: `?sort.desc=id`.'
          nullable: true
      x-tzkt-extension: query-parameter
    BakingRightStatusParameter:
      type: object
      additionalProperties: false
      properties:
        eq:
          type: string
          description: '**Equal** filter mode (optional, i.e. `param.eq=123` is the same as `param=123`). \

            Specify baking right status to get items where the specified field is equal to the specified value.


            Example: `?type=future`.'
          nullable: true
        ne:
          type: string
          description: '**Not equal** filter mode. \

            Specify baking right status to get items where the specified field is not equal to the specified value.


            Example: `?type.ne=missed`.'
          nullable: true
      x-tzkt-extension: query-parameter
      x-tzkt-query-parameter: future,realized,uncovered,missed
    Int32NullParameter:
      type: object
      additionalProperties: false
      properties:
        eq:
          type: integer
          description: '**Equal** filter mode (optional, i.e. `param.eq=123` is the same as `param=123`). \

            Specify an integer number to get items where the specified field is equal to the specified value.


            Example: `?balance=1234`.'
          format: int32
          nullable: true
        ne:
          type: integer
          description: '**Not equal** filter mode. \

            Specify an integer number to get items where the specified field is not equal to the specified value.


            Example: `?balance.ne=1234`.'
          format: int32
          nullable: true
        gt:
          type: integer
          description: '**Greater than** filter mode. \

            Specify an integer number to get items where the specified field is greater than the specified value.


            Example: `?balance.gt=1234`.'
          format: int32
          nullable: true
        ge:
          type: integer
          description: '**Greater or equal** filter mode. \

            Specify an integer number to get items where the specified field is greater than equal to the specified value.


            Example: `?balance.ge=1234`.'
          format: int32
          nullable: true
        lt:
          type: integer
          description: '**Less than** filter mode. \

            Specify an integer number to get items where the specified field is less than the specified value.


            Example: `?balance.lt=1234`.'
          format: int32
          nullable: true
        le:
          type: integer
          description: '**Less or equal** filter mode. \

            Specify an integer number to get items where the specified field is less than or equal to the specified value.


            Example: `?balance.le=1234`.'
          format: int32
          nullable: true
        in:
          type: array
          description: '**In list** (any of) filter mode. \

            Specify a comma-separated list of integers to get items where the specified field is equal to one of the specified values.


            Example: `?level.in=12,14,52,69`.'
          nullable: true
          items:
            type: integer
            format: int32
        ni:
          type: array
          description: '**Not in list** (none of) filter mode. \

            Specify a comma-separated list of integers to get items where the specified field is not equal to all the specified values.


            Example: `?level.ni=12,14,52,69`.'
          nullable: true
          items:
            type: integer
            format: int32
        'null':
          type: boolean
          description: '**Is null** filter mode. \

            Use this mode to get items where the specified field is null or not.


            Example: `?nonce.null` or `?nonce.null=false`.'
          nullable: true
      x-tzkt-extension: query-parameter
    OffsetParameter:
      type: object
      additionalProperties: false
      properties:
        el:
          type: integer
          description: '**Elements** offset mode (optional, i.e. `offset.el=123` is the same as `offset=123`). \

            Skips specified number of elements.


            Example: `?offset=100`.'
          format: int32
          nullable: true
        pg:
          type: integer
          description: '**Page** offset mode. \

            Skips `page * limit` elements. This is a classic pagination.


            Example: `?offset.pg=1`.'
          format: int32
          nullable: true
        cr:
          type: integer
          description: '**Cursor** offset mode. \

            Skips all elements with the `cursor` before (including) the specified value. Cursor is a field used for sorting, e.g. `id`.

            Avoid using this offset mode with non-unique or non-sequential cursors such as `amount`, `balance`, etc.


            Example: `?offset.cr=45837`.'
          format: int64
          nullable: true
      x-tzkt-extension: query-parameter
    AccountParameter:
      type: object
      additionalProperties: false
      properties:
        eq:
          type: string
          description: '**Equal** filter mode (optional, i.e. `param.eq=123` is the same as `param=123`). \

            Specify a `tz` or `KT` address to get items where the specified field is equal to the specified value.


            Example: `?sender=tz1WnfXMPaNTBmH7DBPwqCWs9cPDJdkGBTZ8`.'
          nullable: true
        ne:
          type: string
          description: '**Not equal** filter mode. \

            Specify a `tz` or `KT` address to get items where the specified field is not equal to the specified value.


            Example: `?sender.ne=tz1WnfXMPaNTBmH7DBPwqCWs9cPDJdkGBTZ8`.'
          nullable: true
        in:
          type: array
          description: '**In list** (any of) filter mode. \

            Specify a comma-separated list of addresses to get items where the specified field is equal to one of the specified values.


            Example: `?sender.in=tz1WnfXMPaNTBWnfXMPaNTBWnfXMPaNTBNTB,tz1SiPXX4MYGNJNDSiPXX4MYGNJNDSiPXX4M`.'
          nullable: true
          items:
            type: string
        ni:
          type: array
          description: '**Not in list** (none of) filter mode. \

            Specify a comma-separated list of addresses to get items where the specified field is not equal to all the specified values.


            Example: `?sender.ni=tz1WnfXMPaNTBWnfXMPaNTBWnfXMPaNTBNTB,tz1SiPXX4MYGNJNDSiPXX4MYGNJNDSiPXX4M`.'
          nullable: true
          items:
            type: string
        eqx:
          type: string
          description: '**Equal to another field** filter mode. \

            Specify a field name to get items where the specified fields are equal.


            Example: `?sender.eqx=target`.'
          nullable: true
        nex:
          type: string
          description: '**Not equal to another field** filter mode. \

            Specify a field name to get items where the specified fields are not equal.


            Example: `?sender.nex=initiator`.'
          nullable: true
        'null':
          type: boolean
          description: '**Is null** filter mode. \

            Use this mode to get items where the specified field is null or not.


            Example: `?initiator.null` or `?initiator.null=false`.'
          nullable: true
        inHasNull:
          type: boolean
        niHasNull:
          type: boolean
      x-tzkt-extension: query-parameter
    BakingRight:
      type: object
      additionalProperties: false
      properties:
        type:
          type: string
          description: 'Type of the right:

            - `baking` - right to bake (produce) a block;

            - `attestation` - right to attest (validate) a block.'
        cycle:
          type: integer
          description: Cycle on which the right can be realized.
          format: int32
        level:
          type: integer
          description: Level at which a block must be baked or an attestation must be sent.
          format: int32
        timestamp:
          type: string
          description: Time (estimated, in case of future rights) when a block must be baked or an attestation must be sent.
          format: date-time
        round:
          type: integer
          description: 'Round (0 - ∞) at which the baker can propose/produce a block.

            If a baker at round  `0` doesn''t produce a block within the given time interval, then the right goes to a baker at round` 1`, etc.

            For `attestation` rights this field is always `null`.'
          format: int32
          nullable: true
        slots:
          type: integer
          description: Number of slots to be attested. For `baking` rights this field is always `null`.
          format: int32
          nullable: true
        baker:
          description: Baker to which baking or attestation right has been given.
          oneOf:
          - $ref: '#/components/schemas/Alias'
        status:
          type: string
          description: 'Status of the baking or attestation right:

            - `future` - the right is not realized yet;

            - `realized` - the right was successfully realized;

            - `missed` - the right was not realized.'
    Int32Parameter:
      type: object
      additionalProperties: false
      properties:
        eq:
          type: integer
          description: '**Equal** filter mode (optional, i.e. `param.eq=123` is the same as `param=123`). \

            Specify an integer number to get items where the specified field is equal to the specified value.


            Example: `?balance=1234`.'
          format: int32
          nullable: true
        ne:
          type: integer
          description: '**Not equal** filter mode. \

            Specify an integer number to get items where the specified field is not equal to the specified value.


            Example: `?balance.ne=1234`.'
          format: int32
          nullable: true
        gt:
          type: integer
          description: '**Greater than** filter mode. \

            Specify an integer number to get items where the specified field is greater than the specified value.


            Example: `?balance.gt=1234`.'
          format: int32
          nullable: true
        ge:
          type: integer
          description: '**Greater or equal** filter mode. \

            Specify an integer number to get items where the specified field is greater than equal to the specified value.


            Example: `?balance.ge=1234`.'
          format: int32
          nullable: true
        lt:
          type: integer
          description: '**Less than** filter mode. \

            Specify an integer number to get items where the specified field is less than the specified value.


            Example: `?balance.lt=1234`.'
          format: int32
          nullable: true
        le:
          type: integer
          description: '**Less or equal** filter mode. \

            Specify an integer number to get items where the specified field is less than or equal to the specified value.


            Example: `?balance.le=1234`.'
          format: int32
          nullable: true
        in:
          type: array
          description: '**In list** (any of) filter mode. \

            Specify a comma-separated list of integers to get items where the specified field is equal to one of the specified values.


            Example: `?level.in=12,14,52,69`.'
          nullable: true
          items:
            type: integer
            format: int32
        ni:
          type: array
          description: '**Not in list** (none of) filter mode. \

            Specify a comma-separated list of integers to get items where the specified field is not equal to all the specified values.


            Example: `?level.ni=12,14,52,69`.'
          nullable: true
          items:
            type: integer
            format: int32
      x-tzkt-extension: query-parameter
    SelectParameter:
      type: object
      additionalProperties: false
      properties:
        fields:
          type: array
          description: '**Fields** selection mode (optional, i.e. `select.fields=balance` is the same as `select=balance`). \

            Specify a comma-separated list of fields to include into response.


            Example: `?select=address,balance` => `[ { "address": "asd", "balance": 10 } ]`.'
          nullable: true
          items:
            type: string
        values:
          type: array
          description: '**Values** selection mode. \

            Specify a comma-separated list of fields to include their values into response.


            Example: `?select.values=address,balance` => `[ [ "asd", 10 ] ]`.'
          nullable: true
          items:
            type: string
      x-tzkt-extension: query-parameter
x-generator: NSwag v14.2.0.0 (NJsonSchema v11.1.0.0 (Newtonsoft.Json v13.0.0.0))
x-tagGroups:
- name: REST API
  tags:
  - Accounts
  - BigMaps
  - Blocks
  - Commitments
  - Constants
  - Contracts
  - Cycles
  - Delegates
  - Domains
  - Events
  - Head
  - Helpers
  - Operations
  - Protocols
  - Quotes
  - Rewards
  - Rights
  - SmartRollups
  - Software
  - Staking
  - Statistics
  - Tickets
  - Tokens
  - Voting
- name: WebSocket API
  tags:
  - Get Started
  - Subscriptions
  - Examples
- name: Libraries
  tags:
  - Typescript SDK
  - Taquito extension