Starknet

Skill based on Starknet specs (starkware-libs/starknet-specs), generated from sources/starknet. Doc path: sources/starknet/ (README.md, starknet_vs_ethereum_node_apis.md, api/release.md, api/*.json, wallet-api/wallet_rpc.json).

Starknet specifications define the node JSON-RPC API (read, write, trace, WebSocket) and the Wallet RPC for dApp–wallet interaction. The node API mirrors Ethereum naming with a starknet_ prefix and uses field elements, block tags, and structured errors. Use this skill when implementing or calling Starknet RPC clients, indexers, or wallet integrations.

Core References

Features

Node API

Wallet

Best Practices

Generation Info

• Source: sources/starknet
• Git SHA: 7a89e135bf65d11eb1673d67a06e5cd829973c3d
• Generated: 2026-02-24
• Doc path: sources/starknet/ (README.md, starknet_vs_ethereum_node_apis.md, api/release.md, api/*.json, wallet-api/wallet_rpc.json)

API Versioning and Releases

The Starknet node API specification follows a phased release process. Understanding it helps when implementing clients or relying on a specific API version.

Phases

1. Draft — Work in progress. Expect major changes (types, methods added/changed/removed). There should be only one draft at a time (tip of master). 2. Release Candidate (RC) — Spec is ready to implement or has at least one implementation. Expect minor changes only; no addition/removal of methods. Multiple RCs possible (rc1, rc2, …). 3. Recommendation — Agreed, stable version; expected to be implemented and operated by nodes. No suffix in version tag.

Transitions

• Draft → RC: All changes from the previous release discussed, no pending items; no open PRs for major changes.
• RC → Recommendation: At least 7 working days since the latest RC; no open discussion points.

Version Numbering

• Semantic versioning: major.minor.patch.
• Suffix for RCs: rc1, rc2, … (e.g. 0.10.0-rc1).
• No suffix means Recommendation (e.g. v1.0.0).

When updating the spec version, the version property must be updated in all API specification files and in package*.json (e.g. npm version <VERSION> --no-git-tag-version).

Technical Implementation

• Releases are published as GitHub releases on the starknet-specs repo.
• Git tags on master denote releases: v{major}.{minor}.{patch}[-suffix].
• All API specification documents share the same release version (single logical document).

Usage for Agents

• When documenting or implementing the API, refer to a specific spec version (e.g. from starknet_specVersion or release tags) to avoid drift from Draft.
• For production clients, prefer a Recommendation or a fixed RC version; handle starknet_specVersion in responses to detect node spec version.
• When contributing or reviewing spec changes, respect the phase rules (no major changes after RC).

<!-- Source references:

• https://github.com/starkware-libs/starknet-specs api/release.md

-->

Starknet Overview and Types

Starknet specifications (starknet-specs repo) define the JSON-RPC API for Starknet full nodes. The API is similar to Ethereum's execution API but uses Starknet-specific types and conventions.

Key Concepts

• Field element: The fundamental type. All hashes (block, transaction), addresses, and storage values are field elements. Value range: 0 ≤ x < P where P = 2^251 + 17·2^192 + 1 (Cairo VM field).
• Block tags: Only latest is supported (no earliest or pending like Ethereum).
• Naming: Method names mirror Ethereum with the eth_ prefix replaced by starknet_ (e.g. eth_call → starknet_call).
• Result key: Responses use the key "result" (and "events" for starknet_getEvents). Invalid requests return errors rather than null.

Block and Transaction Objects

Block and transaction structures differ from Ethereum due to different network mechanics (e.g. no proof of work). Use the OpenRPC schemas for exact shapes: BLOCK_ID, BLOCK_WITH_TX_HASHES, BLOCK_WITH_TXS, transaction and receipt types.

Block ID

A block is identified by block_id: either a block hash (field element), block number (decimal integer), or the tag "latest".

{ "block_hash": "0x..." }
{ "block_number": 12345 }
{ "block_tag": "latest" }

Usage

• When implementing or calling the node API, use field elements (hex string or decimal) for addresses, hashes, and storage keys.
• Prefer block_id with "block_tag": "latest" when you need the current state.
• Handle API errors explicitly; the spec returns structured errors (e.g. BLOCK_NOT_FOUND, CONTRACT_NOT_FOUND) instead of null results.

<!-- Source references:

• https://github.com/starkware-libs/starknet-specs (README, starknet_vs_ethereum_node_apis.md)
• api/starknet_api_openrpc.json

-->

RPC Method Mapping (Ethereum → Starknet)

Starknet's node API maps one-to-one from Ethereum method names by replacing the eth_ prefix with starknet_. Below are the main mappings and Starknet-specific differences.

Mapping Table

Agent Usage

• When translating Ethereum RPC code to Starknet, replace eth_* with starknet_* and adapt parameter names (e.g. transaction_hash, contract_address).
• Use block_id (object with block_hash, block_number, or block_tag) instead of a raw block number or tag string where the spec requires it.
• Expect errors instead of null for missing blocks or transactions; handle BLOCK_NOT_FOUND, CONTRACT_NOT_FOUND, etc.

<!-- Source references:

• https://github.com/starkware-libs/starknet-specs/blob/master/starknet_vs_ethereum_node_apis.md

-->

Executables API

The Starknet Executables API (schema: starknet_executables.json) provides access to compiled contract bytecode (CASM) for declared classes.

starknet_getCompiledCasm

Returns the compiled CASM (Cairo Assembly) for a given class.

• Params: Defined in the schema (typically class_hash and possibly block_id or similar).
• Result: Compiled CASM representation (structure in schema).
• Errors: Class not found or not declared.

Use for: verification of on-chain class bytecode, debugging compilation, or tooling that needs the exact CASM (e.g. for security or compatibility checks).

Usage for Agents

• Call this when you need the CASM of a declared class (e.g. to compare with a local build or to inspect bytecode).
• Class must already be declared on chain; otherwise the method returns an error.
• Schema details (param names, result shape) are in api/starknet_executables.json.

<!-- Source references:

• https://github.com/starkware-libs/starknet-specs api/starknet_executables.json

-->

Node Read API

The Starknet Node API (OpenRPC schema: starknet_api_openrpc.json) provides read-only methods for blocks, transactions, state, and chain info. All methods use JSON-RPC 2.0; response result key is "result" (except starknet_getEvents which uses "events").

Spec and Chain Info

• starknet_specVersion — Returns the JSON-RPC spec version (semver string). No params.
• starknet_blockNumber — Latest accepted block number. Errors with NO_BLOCKS if none.
• starknet_blockHashAndNumber — Latest block hash and number. Errors: NO_BLOCKS.
• starknet_chainId — Chain ID. No params.
• starknet_syncing — Syncing status (object). No params.

Blocks

• starknet_getBlockWithTxHashes — Block + transaction hashes. Params: block_id. Errors: BLOCK_NOT_FOUND.
• starknet_getBlockWithTxs — Block + full transactions. Params: block_id.
• starknet_getBlockWithReceipts — Block + full transactions + receipts. Params: block_id.
• starknet_getBlockTransactionCount — Transaction count for block. Params: block_id. Errors: BLOCK_NOT_FOUND.
• starknet_getStateUpdate — State update for block. Params: block_id. Errors: BLOCK_NOT_FOUND.

Transactions and Receipts

• starknet_getTransactionByHash — Transaction by hash. Params: transaction_hash. Errors (no null): invalid hash.
• starknet_getTransactionByBlockIdAndIndex — Transaction by block and index. Params: block_id, index.
• starknet_getTransactionReceipt — Receipt by transaction hash. Params: transaction_hash. Errors (no null): invalid hash.
• starknet_getTransactionStatus — Status for a transaction. Params: transaction_hash.
• starknet_getMessagesStatus — Status for L1→L2 messages. Params: array of message identifiers.
• starknet_pendingTransactions — Pending transactions (result key "result"; no market fee params).

State and Contracts

• starknet_getStorageAt — Storage value at contract + key. Params: contract_address, key, block_id. Result: field element. Errors: invalid contract or key.
• starknet_getCode — Contract bytecode (field elements) and ABI. Params: contract_address. No block; errors on invalid address.
• starknet_getClass — Class definition by hash. Params: block_id, class_hash.
• starknet_getClassHashAt — Class hash at address. Params: block_id, contract_address.
• starknet_getClassAt — Class definition at address. Params: block_id, contract_address.
• starknet_getNonce — Nonce at address in block. Params: block_id, contract_address. Errors: BLOCK_NOT_FOUND, CONTRACT_NOT_FOUND.
• starknet_getStorageProof — Merkle paths for state/classes/contract storage. Params: block_id (no pre_confirmed), optional class_hashes, contract_addresses, storage_keys. Single request can mix proof types.

Call and Events

• starknet_call — Execute a view/pure call (no state change). Params: request (FUNCTION_CALL: contract_address, entry_point_selector, calldata), block_id. Result: array of field elements (Cairo return). Errors: CONTRACT_NOT_FOUND, ENTRYPOINT_NOT_FOUND, CONTRACT_ERROR, BLOCK_NOT_FOUND.
• starknet_getEvents — Events matching filter. Params: filter (EVENT_FILTER + RESULT_PAGE_REQUEST). Result key: "events" (EVENTS_CHUNK). Errors: PAGE_SIZE_TOO_BIG, INVALID_CONTINUATION_TOKEN, BLOCK_NOT_FOUND, TOO_MANY_KEYS_IN_FILTER.

Example: starknet_call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "starknet_call",
  "params": {
    "request": {
      "contract_address": "0x...",
      "entry_point_selector": "0x...",
      "calldata": ["0x..."]
    },
    "block_id": { "block_tag": "latest" }
  }
}

Response: "result": [ "0x...", "0x..." ] (array of felt).

Usage for Agents

• Use block_id with block_tag: "latest" for current state when no specific block is needed.
• For getCode/getClass, note that starknet_getCode does not take a block_id; class methods do.
• Prefer starknet_getBlockWithReceipts when both block and receipt data are needed in one call.
• Handle BLOCK_NOT_FOUND, CONTRACT_NOT_FOUND, and CONTRACT_ERROR when building robust clients.

<!-- Source references:

• https://github.com/starkware-libs/starknet-specs api/starknet_api_openrpc.json
• starknet_vs_ethereum_node_apis.md

-->

Node Write API

The Starknet Write API (schema: starknet_write_api.json) provides methods to submit transactions to the network. These are the main ways to change state or deploy contracts.

Methods

starknet_addInvokeTransaction

Submits an invoke transaction (e.g. calling a contract or sending tokens).

• Params: Transaction payload conforming to the write API schema (e.g. sender, calldata, signature, nonce, max_fee, etc.).
• Result: Transaction hash (and possibly other metadata per schema).
• Errors: Validation or execution errors as defined in the schema.

Use for: single contract calls, multi-calls from an account contract.

starknet_addDeclareTransaction

Submits a declare transaction to register a new contract class (Cairo/Sierra) on chain.

• Params: Declare transaction payload (class data, sender, signature, nonce, max_fee, etc.).
• Result: Transaction hash and class hash (per schema).
• Errors: Invalid class, duplicate class, validation errors.

Use for: deploying new contract code (class) that can later be instantiated.

starknet_addDeployAccountTransaction

Submits a deploy_account transaction to deploy an account contract (create contract from class at a precomputed address).

• Params: Deploy account transaction payload (class hash, contract address salt, constructor calldata, signature, nonce, max_fee, etc.).
• Result: Transaction hash and deployed contract address (per schema).
• Errors: Invalid class, address already in use, validation errors.

Use for: creating an account contract (or any contract) from a declared class.

Usage for Agents

• Ensure transaction payloads match the OpenRPC schema in starknet_write_api.json (exact field names and types).
• Invoke: use for state-changing calls; estimate fees first with starknet_estimateFee (read API).
• Declare then deploy: first starknet_addDeclareTransaction to register the class, then starknet_addDeployAccountTransaction (or deploy via invoke where applicable) to create instances.
• Handle schema-defined errors for validation and execution failures.

<!-- Source references:

• https://github.com/starkware-libs/starknet-specs api/starknet_write_api.json

-->

Trace API

The Starknet Trace API (schema: starknet_trace_api_openrpc.json) provides execution traces and transaction simulation. Use it for debugging, fee estimation insight, and understanding execution flow.

Methods

starknet_traceTransaction

Returns the execution trace for a given transaction.

• Params: transaction_hash (and any other params defined in the schema).
• Result: Trace object (structure in schema: function calls, internal calls, execution steps).
• Errors: Invalid or missing transaction.

Use for: debugging a single transaction, building trace-based tooling.

starknet_simulateTransactions

Simulates a sequence of transactions on a given state without submitting them.

• Params: Array of transactions to simulate (same shape as for starknet_estimateFee), simulation flags, and block_id (and any extra params in schema).
• Result: Simulation result per transaction (e.g. trace, fee, revert info).
• Errors: Invalid block, contract, or execution failure.

Use for: dry runs, fee estimation, and validating transaction sequences before broadcast.

starknet_traceBlockTransactions

Returns traces for all transactions in a block.

• Params: block_id (and any other params in schema).
• Result: Array or map of transaction hash to trace (see schema).
• Errors: BLOCK_NOT_FOUND or invalid block.

Use for: block-level analysis and indexing execution data.

Usage for Agents

• Prefer starknet_simulateTransactions when you need both trace and fee/outcome without sending transactions.
• Trace results follow the OpenRPC schema types; use them to walk internal calls and identify reverts or heavy steps.
• Combine with the read API: use starknet_getBlockWithTxs then starknet_traceBlockTransactions to correlate traces with transaction data.

<!-- Source references:

• https://github.com/starkware-libs/starknet-specs api/starknet_trace_api_openrpc.json

-->

Wallet API

The Starknet Wallet API (schema: wallet-api/wallet_rpc.json) is used by dApps to interact with Starknet wallets (browser extensions, mobile apps). It is separate from the node JSON-RPC; wallets implement this API for the dApp to call.

Capability Discovery

• wallet_supportedWalletApi — Returns wallet API versions supported by the wallet (semver list). No params. Result: array of API_VERSION.
• wallet_supportedSpecs — Returns Starknet JSON-RPC spec versions supported by the wallet. No params. Result: array of SPEC_VERSION.

Use these to detect compatibility before calling account or signing methods.

Permissions and Accounts

• wallet_getPermissions — Returns existing permissions for the dApp. Params: optional api_version. Result: array of PERMISSION or empty. Errors: API_VERSION_NOT_SUPPORTED, UNKNOWN_ERROR.
• wallet_requestAccounts — Requests account addresses (e.g. opens unlock/approve UI). Params: optional silent_mode (if true, no UI; returns empty array when locked or not approved). Result: array of account addresses. When wallet locked: unlock UI; when dApp not approved: approve UI; when connected and unlocked: return addresses.

Use wallet_requestAccounts to connect the dApp to the wallet and obtain addresses for display or for building transactions.

Signing and Transactions

The schema defines further methods for signing messages and transactions (e.g. request signature for a transaction or typed data). Exact method names and params are in wallet_rpc.json (e.g. sign message, send transaction).

• When implementing dApp flows: (1) call wallet_supportedSpecs / wallet_supportedWalletApi, (2) call wallet_requestAccounts, (3) use returned addresses with the node’s Write API to build and then sign/send via wallet methods.
• Respect silent_mode: when true, do not expect UI; handle empty or denied responses.

Usage for Agents

• Wallet RPC is invoked by the dApp on the wallet provider (e.g. injected window.starknet), not on the Starknet node.
• For agents that generate dApp code, ensure compatibility checks use wallet_supportedSpecs and handle version mismatches.
• Reference wallet-api/wallet_rpc.json for the full list of methods, params, and error codes.

<!-- Source references:

• https://github.com/starkware-libs/starknet-specs wallet-api/wallet_rpc.json

-->

WebSocket API

The Starknet WebSocket API (schema: starknet_ws_api.json) allows clients to subscribe to real-time updates: new blocks, events, transaction status, new transaction receipts, new transactions, and reorgs.

Subscription Methods

• starknet_subscribeNewHeads — New block headers. Params per schema (if any). Returns subscription id.
• starknet_subscriptionNewHeads — Subscription type for new heads (used in subscription notifications).
• starknet_subscribeEvents — Events matching a filter. Params: event filter. Returns subscription id.
• starknet_subscriptionEvents — Subscription type for events.
• starknet_subscribeTransactionStatus — Status updates for a transaction. Params: transaction hash(es) or identifier. Returns subscription id.
• starknet_subscriptionTransactionStatus — Subscription type for transaction status.
• starknet_subscribeNewTransactionReceipts — New transaction receipts as they are finalized. Returns subscription id.
• starknet_subscriptionNewTransactionReceipts — Subscription type for new receipts.
• starknet_subscribeNewTransactions — New transactions (e.g. pending or accepted). Returns subscription id.
• starknet_subscriptionNewTransaction — Subscription type for new transactions.
• starknet_subscriptionReorg — Reorganization notifications (block reorgs).
• starknet_unsubscribe — Unsubscribe by subscription id. Params: subscription id.

Usage for Agents

• Use WebSocket when building indexers, dashboards, or bots that need real-time block/event/tx updates.
• Connect to the node’s WebSocket endpoint (see node docs), then send JSON-RPC requests with method starknet_subscribe*; the server will push notifications with the corresponding starknet_subscription* type.
• Always pair subscriptions with starknet_unsubscribe when disconnecting or cleaning up to avoid leaking server-side state.
• For event subscriptions, pass the same filter shape used in starknet_getEvents (EVENT_FILTER) where applicable.

<!-- Source references:

• https://github.com/starkware-libs/starknet-specs api/starknet_ws_api.json

-->