starknet_ws_api.json

{
  "openrpc": "1.3.2",
  "info": {
    "version": "0.8.0-rc0",
    "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": "./api/starknet_api_openrpc.json#/components/schemas/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"
        },
        {
            "$ref": "#/components/errors/CALL_ON_PENDING"
        }
      ]
    },
    {
      "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",
      "params": [
        {
          "name": "from_address",
          "summary": "Filter events by from_address which emitted the event",
          "required": false,
          "schema": {
            "$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": "./api/starknet_api_openrpc.json#/components/schemas/BLOCK_ID"
          }
        }
      ],
      "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"
        },
        {
            "$ref": "#/components/errors/CALL_ON_PENDING"
        }
      ]
    },
    {
      "name": "starknet_subscriptionEvents",
      "summary": "New events notification",
      "description": "Notification to the client of a new event",
      "params": [
        {
          "name": "subscription_id",
          "schema": {
            "$ref": "#/components/schemas/SUBSCRIPTION_ID"
          }
        },
        {
          "name": "result",
          "schema": {
            "$ref": "./api/starknet_api_openrpc.json#/components/schemas/EMITTED_EVENT"
          }
        }
      ],
      "errors": []
    },
    {
      "name": "starknet_subscribeTransactionStatus",
      "summary": "Transaction Status subscription",
      "description": "Creates a WebSocket stream which will fire events when a transaction status is updated",
      "params": [
        {
          "name": "transaction_hash",
          "summary": "The transaction hash to fetch status updates for",
          "required": true,
          "schema": {
            "$ref": "#/components/schemas/FELT"
          }
        },
        {
          "name": "block_id",
          "summary": "The block to get notifications from, default is latest, limited to 1024 blocks back",
          "required": false,
          "schema": {
            "$ref": "./api/starknet_api_openrpc.json#/components/schemas/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_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_subscribePendingTransactions",
      "summary": "New Pending Transactions subscription",
      "description": "Creates a WebSocket stream which will fire events when a new pending transaction is added. While there is no mempool, this notifies of transactions in the pending block",
      "params": [
        {
          "name": "transaction_details",
          "summary": "Get all transaction details, and not only the hash. If not provided, only hash is returned. Default is false",
          "required": false,
          "schema": {
            "type": "boolean"
          }
        },
        {
          "name": "sender_address",
          "summary": "Filter transactions to only receive notification from address list",
          "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_subscriptionPendingTransactions",
      "summary": "New pending transaction notification",
      "description": "Notification to the client of a new pending transaction",
      "params": [
        {
          "name": "subscription_id",
          "schema": {
            "$ref": "#/components/schemas/SUBSCRIPTION_ID"
          }
        },
        {
          "name": "result",
          "description": "Either a tranasaction hash or full transaction details, based on subscription",
          "schema": {
            "oneOf": [
              {
                "$ref": "./api/starknet_api_openrpc.json#/components/schemas/TXN_HASH"
              },
              {
                "$ref": "./api/starknet_api_openrpc.json#/components/schemas/TXN"
              }
            ]
          }
        }
      ],
      "errors": []
    },
    {
      "name": "starknet_subscriptionReorg",
      "description": "Notifies the subscriber of a reorganization of the chain",
      "summary": "Can be received from subscribing to newHeads, Events, TransactionStatus",
      "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": {
            "type": "integer"
          }
        }
      ],
      "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": {
            "schema": {
              "$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": "integer"
        }
      },
      "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",
            "schema": {
              "$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",
            "schema": {
              "$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"
      },
      "CALL_ON_PENDING": {
        "code": 69,
        "message": "This method does not support being called on the pending block"
      }
    }
  }
}