Transactions - NEAR Protocol

The RPC API enables you to send transactions and query their status on the NEAR blockchain. This includes sending new transactions, checking transaction status, retrieving receipts, and monitoring transaction execution.

Quick Reference

Method	Parameters	Description
`send_tx`	`signed_tx_base64`, `wait_until`	Send a transaction and optionally wait for execution
`tx`	`tx_hash`, `sender_account_id`, `wait_until`	Query transaction status by hash
`EXPERIMENTAL_tx_status`	`tx_hash`, `sender_account_id`, `wait_until`	Query transaction status with receipt details
`EXPERIMENTAL_receipt`	`receipt_id`	Fetch receipt by ID
`broadcast_tx_async`	`signed_tx_base64`	(Deprecated) Send transaction asynchronously
`broadcast_tx_commit`	`signed_tx_base64`	(Deprecated) Send transaction and wait for completion

Send transaction

Sends transaction. Returns the guaranteed execution status and the results the blockchain can provide at the moment.

method

string

required

send_tx

signed_tx_base64

string

required

SignedTransaction encoded in base64

wait_until

string

The required minimal execution level. Default value is EXECUTED_OPTIMISTIC. Read more here.

Using send_tx with wait_until = NONE is equal to legacy broadcast_tx_async method. Using send_tx with wait_until = EXECUTED_OPTIMISTIC is equal to legacy broadcast_tx_commit method.

{
  "jsonrpc": "2.0",
  "id": "dontcare",
  "method": "send_tx",
  "params": {
    "signed_tx_base64": "DgAAAHNlbmRlci50ZXN0bmV0AOrmAai64SZOv9e/naX4W15pJx0GAap35wTT1T/DwcbbDwAAAAAAAAAQAAAAcmVjZWl2ZXIudGVzdG5ldNMnL7URB1cxPOu3G8jTqlEwlcasagIbKlAJlF5ywVFLAQAAAAMAAACh7czOG8LTAAAAAAAAAGQcOG03xVSFQFjoagOb4NBBqWhERnnz45LY4+52JgZhm1iQKz7qAdPByrGFDQhQ2Mfga8RlbysuQ8D8LlA6bQE=",
    "wait_until": "INCLUDED_FINAL"
  }
}

Transaction Status

Queries status of a transaction by hash and returns the final transaction result.

method

string

required

tx

tx_hash

string

required

Transaction hash (see NearBlocks Explorer for valid hashes)

sender_account_id

string

required

Used to determine which shard to query for transaction

wait_until

string

The required minimal execution level. Default is EXECUTED_OPTIMISTIC. Read more here.

A Transaction status request with wait_until != NONE will wait until the transaction appears on the blockchain. If the transaction does not exist, the method will wait until the timeout is reached. If you only need to check whether the transaction exists, use wait_until = NONE, it will return the response immediately.

{
  "jsonrpc": "2.0",
  "id": "dontcare",
  "method": "tx",
  "params": {
    "tx_hash": "7AfonAhbK4ZbdBU9VPcQdrTZVZBXE25HmZAMEABs9To1",
    "sender_account_id": "rpc-examples.testnet",
    "wait_until": "FINAL"
  }
}

Transaction Status with Receipts

Queries status of a transaction by hash, returning the final transaction result and details of all receipts.

method

string

required

EXPERIMENTAL_tx_status

tx_hash

string

required

Transaction hash

sender_account_id

string

required

Used to determine which shard to query for transaction

wait_until

string

The required minimal execution level. Default is EXECUTED_OPTIMISTIC.

Receipt by ID

Fetches a receipt by its ID (as is, without a status or execution outcome).

method

string

required

EXPERIMENTAL_receipt

receipt_id

string

required

Receipt ID (see NearBlocks Explorer for valid receipt IDs)

{
  "jsonrpc": "2.0",
  "id": "dontcare",
  "method": "EXPERIMENTAL_receipt",
  "params": {
    "receipt_id": "23r1wWsMAVtZysr9wNV6TCSdZTUyPbhBZ3McJ6zStpaE"
  }
}

Transaction Execution Levels

All the methods listed above have wait_until request parameter, and final_execution_status response value. They correspond to the same enum TxExecutionStatus. See the detailed explanation for all the options:

#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
pub enum TxExecutionStatus {
  /// Transaction is waiting to be included into the block
  None,
  /// Transaction is included into the block. The block may be not finalized yet
  Included,
  /// Transaction is included into the block +
  /// All non-refund transaction receipts finished their execution.
  /// The corresponding blocks for tx and each receipt may be not finalized yet
  #[default]
  ExecutedOptimistic,
  /// Transaction is included into finalized block
  IncludedFinal,
  /// Transaction is included into finalized block +
  /// All non-refund transaction receipts finished their execution.
  /// The corresponding blocks for each receipt may be not finalized yet
  Executed,
  /// Transaction is included into finalized block +
  /// Execution of all transaction receipts is finalized, including refund receipts
  Final,
}

Show Waiting for a Transaction

When a transaction is submitted, it first gets validated by the RPC node. If the transaction fails structural checks it will be immediately rejected. Otherwise, it enters the following lifecycle:

The transaction has been accepted by the RPC node and is waiting to be included in a block. If wait_until = None, the RPC will return a response at this stage. The transaction hasn’t started executing yet, though it will typically start in the next block.
Once the transaction reaches a validator, it ensures a signature matches signer access key and that the account is charged gas pre-payment, then updates access key nonce. The transaction is included in a chunk/block and converted into a single receipt for execution. If wait_until = Included, the RPC returns a response immediately indicating that the transaction has just started the execution (no execution results, logs, and outcomes are available at this point).
In the next blocks, the receipt will get executed and it may produce more receipts for cross-contract interactions. Once all receipts finish the execution, RPC returns a response if wait_until = ExecutedOptimistic.
The block that contains the transaction has been finalized. This may occur even sooner than receipts execution finishes (depending on how many cross-contract interactions there), and when it finishes, the RPC returns a response if wait_until = IncludedFinal.
Once the block that contains the transaction has been finalized and all receipts have completed execution (both IncludedFinal and ExecutedOptimistic are satisfied), then RPC returns a response if wait_until = Executed.
Once blocks containing the transaction and all of its receipts are finalized, the RPC returns a response at this point if wait_until = Final.

Deprecated methods

[deprecated] Send transaction (async)

Consider using send_tx instead.

Sends a transaction and immediately returns transaction hash.

method

string

required

broadcast_tx_async

params

array

required

[SignedTransaction encoded in base64]

[deprecated] Send transaction (await)

Consider using send_tx instead.

Sends a transaction and waits until transaction is fully complete. (Has a 10 second timeout)

method

string

required

broadcast_tx_commit

params

array

required

[SignedTransaction encoded in base64]

Error Handling

Common Error Types

Error Code	Description	Solution
`UnknownTransaction`	Transaction not found	Verify transaction hash and sender account
`TimeoutError`	Transaction timeout	Use appropriate wait_until parameter or retry
`InvalidTransaction`	Invalid transaction format	Check transaction structure and signature
`InvalidAccount`	Invalid account format	Use valid account ID format (e.g., `account.near`)
`InsufficientStake`	Not enough stake for operation	Ensure account has sufficient NEAR tokens
`MethodNotFound`	Invalid method name	Check method spelling and API version
`ParseError`	JSON parsing error	Verify JSON format and structure
`ServerError`	Internal server error	Retry request or use different RPC endpoint

Best Practices

Use appropriate wait_until levels: Choose the right execution level based on your requirements
- NONE: For fire-and-forget scenarios
- INCLUDED: When you need confirmation the transaction is in a block
- EXECUTED_OPTIMISTIC: For most use cases (default)
- FINAL: When you need absolute finality guarantees
Handle timeouts gracefully: Implement proper timeout handling and retry logic
Monitor gas usage: Track gas consumption to optimize transaction costs
Batch operations: When possible, batch multiple actions in a single transaction

RPC API

​Quick Reference

​Send transaction

​Transaction Status

​Transaction Status with Receipts

​Receipt by ID

​Transaction Execution Levels

​Deprecated methods

​[deprecated] Send transaction (async)

​[deprecated] Send transaction (await)

​Error Handling

​Common Error Types

​Best Practices

Build docs developers (and LLMs) love

Quick Reference

Send transaction

Transaction Status

Transaction Status with Receipts

Receipt by ID

Transaction Execution Levels

Deprecated methods

[deprecated] Send transaction (async)

[deprecated] Send transaction (await)

Error Handling

Common Error Types

Best Practices