starknet_ws_api.json

{
  "openrpc": "1.3.2",
  "info": {
    "version": "0.10.1",
    "title": "StarkNet WebSocket RPC API",
    "license": {}
  },
  "methods": [
    {
      "name": "starknet_subscribeNewHeads",
      "summary": "New block headers subscription",
      "description": "Creates a WebSocket stream which will fire events for new block headers",
      "params": [
        {
          "name": "block_id",
          "summary": "The block to get notifications from, default is latest, limited to 1024 blocks back",
          "required": false,
          "schema": {
            "$ref": "#/components/schemas/SUBSCRIPTION_BLOCK_ID"
          }
        }
      ],
      "result": {
        "name": "subscription_id",
        "schema": {
          "$ref": "#/components/schemas/SUBSCRIPTION_ID"
        }
      },
      "errors": [
        {
          "$ref": "#/components/errors/TOO_MANY_BLOCKS_BACK"
        },
        {
          "$ref": "./api/starknet_api_openrpc.json#/components/errors/BLOCK_NOT_FOUND"
        }
      ]
    },
    {
      "name": "starknet_subscriptionNewHeads",
      "summary": "New block headers notification",
      "description": "Notification to the client of a new block header",
      "params": [
        {
          "name": "subscription_id",
          "schema": {
            "$ref": "#/components/schemas/SUBSCRIPTION_ID"
          }
        },
        {
          "name": "result",
          "schema": {
            "$ref": "./api/starknet_api_openrpc.json#/components/schemas/BLOCK_HEADER"
          }
        }
      ],
      "errors": []
    },
    {
      "name": "starknet_subscribeEvents",
      "summary": "Events subscription",
      "description": "Creates a WebSocket stream which will fire events for new Starknet events with applied filters. Events are emitted for all events from the specified block_id, up to the latest block. If PRE_CONFIRMED finality status is provided, events might appear multiple times, for each finality status update. If a single event is required, ACCEPTED_ON_L2 must be selected (the default).",
      "params": [
        {
          "name": "from_address",
          "summary": "Filter events by from_address which emitted the event",
          "description": "A contract address or a list of addresses from which events should originate",
          "required": false,
          "schema": {
            "oneOf": [
              {
                "title": "Single address",
                "$ref": "#/components/schemas/ADDRESS"
              },
              {
                "title": "List of addresses",
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ADDRESS"
                }
              }
            ]
          }
        },
        {
          "name": "keys",
          "summary": "The keys to filter events by",
          "required": false,
          "schema": {
            "title": "event keys",
            "$ref": "./api/starknet_api_openrpc.json#/components/schemas/EVENT_KEYS"
          }
        },
        {
          "name": "block_id",
          "summary": "The block to get notifications from, default is latest, limited to 1024 blocks back",
          "required": false,
          "schema": {
            "$ref": "#/components/schemas/SUBSCRIPTION_BLOCK_ID"
          }
        },
        {
          "name": "finality_status",
          "summary": "The finality status of the most recent events to include, default is ACCEPTED_ON_L2. If PRE_CONFIRMED finality is selected, events might appear multiple times, once for each finality status update.",
          "required": false,
          "schema": {
            "type": "string",
            "enum": ["PRE_CONFIRMED", "ACCEPTED_ON_L2"]
          }
        }
      ],
      "result": {
        "name": "subscription_id",
        "schema": {
          "$ref": "#/components/schemas/SUBSCRIPTION_ID"
        }
      },
      "errors": [
        {
          "$ref": "./api/starknet_api_openrpc.json#/components/errors/TOO_MANY_KEYS_IN_FILTER"
        },
        {
          "$ref": "#/components/errors/TOO_MANY_BLOCKS_BACK"
        },
        {
          "$ref": "./api/starknet_api_openrpc.json#/components/errors/BLOCK_NOT_FOUND"
        }
      ]
    },
    {
      "name": "starknet_subscriptionEvents",
      "summary": "New events notification",
      "description": "Notification to the client of a new event. The event also includes the finality status of the transaction emitting the event",
      "params": [
        {
          "name": "subscription_id",
          "schema": {
            "$ref": "#/components/schemas/SUBSCRIPTION_ID"
          }
        },
        {
          "name": "result",
          "schema": {
            "allOf": [
              {
                "$ref": "./api/starknet_api_openrpc.json#/components/schemas/EMITTED_EVENT"
              },
              {
                "type": "object",
                "properties": {
                  "finality_status": {
                    "description": "Finality status of the transaction",
                    "$ref": "./api/starknet_api_openrpc.json#/components/schemas/TXN_FINALITY_STATUS"
                  }
                },
                "required": ["finality_status"]
              }
            ]
          }
        }
      ],
      "errors": []
    },
    {
      "name": "starknet_subscribeTransactionStatus",
      "summary": "Transaction Status subscription",
      "description": "Creates a WebSocket stream which at first fires an event with the current known transaction status, followed by events for every transaction status update",
      "params": [
        {
          "name": "transaction_hash",
          "summary": "The transaction hash to fetch status updates for",
          "required": true,
          "schema": {
            "$ref": "#/components/schemas/FELT"
          }
        }
      ],
      "result": {
        "name": "subscription_id",
        "schema": {
          "$ref": "#/components/schemas/SUBSCRIPTION_ID"
        }
      },
      "errors": []
    },
    {
      "name": "starknet_subscriptionTransactionStatus",
      "summary": "New transaction status notification",
      "description": "Notification to the client of a new transaction status",
      "params": [
        {
          "name": "subscription_id",
          "schema": {
            "$ref": "#/components/schemas/SUBSCRIPTION_ID"
          }
        },
        {
          "name": "result",
          "schema": {
            "$ref": "#/components/schemas/NEW_TXN_STATUS"
          }
        }
      ],
      "errors": []
    },
    {
      "name": "starknet_subscribeNewTransactionReceipts",
      "summary": "New transactions receipts subscription",
      "description": "Creates a WebSocket stream which will fire events when new transaction receipts are created. The endpoint receives a vector of finality statuses. An event is fired for each finality status update. It is possible for receipts for pre-confirmed transactions to be received multiple times, or not at all.",
      "params": [
        {
          "name": "finality_status",
          "summary": "A vector of finality statuses to receive updates for, default is [ACCEPTED_ON_L2]",
          "required": false,
          "schema": {
            "type": "array",
            "items": {
              "allOf": [
                {
                  "$ref": "./api/starknet_api_openrpc.json#/components/schemas/TXN_FINALITY_STATUS"
                },
                {
                  "not": {
                    "type": "string",
                    "enum": ["ACCEPTED_ON_L1"]
                  }
                }
              ]
            }
          }
        },
        {
          "name": "sender_address",
          "summary": "Filter transaction receipts to only include transactions sent by the specified addresses",
          "required": false,
          "schema": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ADDRESS"
            }
          }
        }
      ],
      "result": {
        "name": "subscription_id",
        "schema": {
          "$ref": "#/components/schemas/SUBSCRIPTION_ID"
        }
      },
      "errors": [
        {
          "$ref": "#/components/errors/TOO_MANY_ADDRESSES_IN_FILTER"
        }
      ]
    },
    {
      "name": "starknet_subscriptionNewTransactionReceipts",
      "summary": "New transaction receipt notification",
      "description": "Notification to the client of a new transaction receipt, with its current finality status",
      "params": [
        {
          "name": "subscription_id",
          "schema": {
            "$ref": "#/components/schemas/SUBSCRIPTION_ID"
          }
        },
        {
          "name": "result",
          "description": "A transaction receipt",
          "schema": {
            "$ref": "./api/starknet_api_openrpc.json#/components/schemas/TXN_RECEIPT_WITH_BLOCK_INFO"
          }
        }
      ],
      "errors": []
    },
    {
      "name": "starknet_subscribeNewTransactions",
      "summary": "New transactions subscription",
      "description": "Creates a WebSocket stream which will fire events when new transaction are created. The endpoint receives a vector of finality statuses. An event is fired for each finality status update. It is possible for events for pre-confirmed and candidate transactions to be received multiple times, or not at all.",
      "params": [
        {
          "name": "finality_status",
          "summary": "A vector of finality statuses to receive updates for, default is [ACCEPTED_ON_L2]",
          "required": false,
          "schema": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TXN_STATUS_WITHOUT_L1"
            }
          }
        },
        {
          "name": "sender_address",
          "summary": "Filter to only include transactions sent by the specified addresses",
          "required": false,
          "schema": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ADDRESS"
            }
          }
        },
        {
          "name": "tags",
          "summary": "Tags that control what additional fields are included in transaction responses",
          "required": false,
          "schema": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SUBSCRIPTION_TAG"
            }
          }
        }
      ],
      "result": {
        "name": "subscription_id",
        "schema": {
          "$ref": "#/components/schemas/SUBSCRIPTION_ID"
        }
      },
      "errors": [
        {
          "$ref": "#/components/errors/TOO_MANY_ADDRESSES_IN_FILTER"
        }
      ]
    },
    {
      "name": "starknet_subscriptionNewTransaction",
      "summary": "New transaction notification",
      "description": "Notification to the client of a new transaction, with its current finality status",
      "params": [
        {
          "name": "subscription_id",
          "schema": {
            "$ref": "#/components/schemas/SUBSCRIPTION_ID"
          }
        },
        {
          "name": "result",
          "description": "A transaction and its current finality status",
          "schema": {
            "allOf": [
              {
                "$ref": "./api/starknet_api_openrpc.json#/components/schemas/TXN_WITH_HASH"
              },
              {
                "type": "object",
                "properties": {
                  "finality_status": {
                    "description": "Finality status of the transaction",
                    "$ref": "#/components/schemas/TXN_STATUS_WITHOUT_L1"
                  }
                },
                "required": ["finality_status"]
              }
            ]
          }
        }
      ],
      "errors": []
    },
    {
      "name": "starknet_subscriptionReorg",
      "description": "Notifies the subscriber of a reorganization of the chain",
      "summary": "Can be received from subscribing to newHeads, Events, TransactionStatus, NewTransactionReceipts, NewTransactions",
      "params": [
        {
          "name": "subscription_id",
          "schema": {
            "$ref": "#/components/schemas/SUBSCRIPTION_ID"
          }
        },
        {
          "name": "result",
          "schema": {
            "$ref": "#/components/schemas/REORG_DATA"
          }
        }
      ]
    },
    {
      "name": "starknet_unsubscribe",
      "summary": "Closes a websocket subscription",
      "description": "Close a previously opened ws stream, with the corresponding subscription id",
      "params": [
        {
          "name": "subscription_id",
          "summary": "The subscription to close",
          "required": true,
          "schema": {
            "$ref": "#/components/schemas/SUBSCRIPTION_ID"
          }
        }
      ],
      "result": {
        "name": "Unsubscription result",
        "description": "True if the unsubscription was successful",
        "schema": {
          "type": "boolean"
        }
      },
      "errors": [
        {
          "$ref": "#/components/errors/INVALID_SUBSCRIPTION_ID"
        }
      ]
    }
  ],
  "components": {
    "schemas": {
      "FELT": {
        "$ref": "./api/starknet_api_openrpc.json#/components/schemas/FELT"
      },
      "ADDRESS": {
        "$ref": "./api/starknet_api_openrpc.json#/components/schemas/ADDRESS"
      },
      "NEW_TXN_STATUS": {
        "title": "New transaction Status",
        "type": "object",
        "properties": {
          "transaction_hash": {
            "$ref": "./api/starknet_api_openrpc.json#/components/schemas/TXN_HASH"
          },
          "status": {
            "$ref": "./api/starknet_api_openrpc.json#/components/schemas/TXN_STATUS_RESULT"
          }
        }
      },
      "SUBSCRIPTION_ID": {
        "name": "subscription id",
        "description": "An identifier for this subscription stream used to associate events with this subscription.",
        "schema": {
          "type": "string"
        }
      },
      "SUBSCRIPTION_BLOCK_ID": {
        "title": "Subscription Block id",
        "description": "Block hash, number or tag, same as BLOCK_ID, but without 'pre_confirmed' or 'l1_accepted'",
        "schema": {
          "title": "Block id",
          "allOf": [
            {
              "$ref": "./api/starknet_api_openrpc.json#/components/schemas/BLOCK_ID"
            },
            {
              "not": {
                "type": "string",
                "enum": ["l1_accepted", "pre_confirmed"]
              }
            }
          ]
        }
      },
      "TXN_STATUS_WITHOUT_L1": {
        "title": "Transaction status without ACCEPTED_ON_L1",
        "description": "Transaction status for new transactions subscription",
        "allOf": [
          {
            "$ref": "./api/starknet_api_openrpc.json#/components/schemas/TXN_STATUS"
          },
          {
            "not": {
              "type": "string",
              "enum": ["ACCEPTED_ON_L1"]
            }
          }
        ]
      },
      "SUBSCRIPTION_TAG": {
        "type": "string",
        "enum": ["INCLUDE_PROOF_FACTS"],
        "description": "Tags that control what additional fields are included in subscription responses. INCLUDE_PROOF_FACTS: Include proof_facts field in the response (an empty array is returned if no proof facts exist for the transaction; only applicable to INVOKE transactions with version 3)."
      },
      "REORG_DATA": {
        "name": "Reorg Data",
        "description": "Data about reorganized blocks, starting and ending block number and hash",
        "properties": {
          "starting_block_hash": {
            "title": "Starting Block Hash",
            "description": "Hash of the first known block of the orphaned chain",
            "$ref": "./api/starknet_api_openrpc.json#/components/schemas/BLOCK_HASH"
          },
          "starting_block_number": {
            "title": "Starting Block Number",
            "description": "Number of the first known block of the orphaned chain",
            "$ref": "./api/starknet_api_openrpc.json#/components/schemas/BLOCK_NUMBER"
          },
          "ending_block_hash": {
            "title": "Ending Block",
            "description": "The last known block of the orphaned chain",
            "$ref": "./api/starknet_api_openrpc.json#/components/schemas/BLOCK_HASH"
          },
          "ending_block_number": {
            "title": "Ending Block Number",
            "description": "Number of the last known block of the orphaned chain",
            "$ref": "./api/starknet_api_openrpc.json#/components/schemas/BLOCK_NUMBER"
          }
        },
        "required": [
          "starting_block_hash",
          "starting_block_number",
          "ending_block_hash",
          "ending_block_number"
        ]
      }
    },
    "errors": {
      "INVALID_SUBSCRIPTION_ID": {
        "code": 66,
        "message": "Invalid subscription id"
      },
      "TOO_MANY_ADDRESSES_IN_FILTER": {
        "code": 67,
        "message": "Too many addresses in filter sender_address filter"
      },
      "TOO_MANY_BLOCKS_BACK": {
        "code": 68,
        "message": "Cannot go back more than 1024 blocks"
      }
    }
  }
}