# Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation This site has an agentic ask interface you may use to query the documentation dynamically by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.novarpc.xyz/index.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. --- # Nova RPC MEV protection and industry leading inclusion for Ethereum and beyond # Overview **Enterprise Grade MEV Protection** Nova is a SOC 2 compliant partner allowing transaction originators to consume public blockspace, without exposing transaction intent publicly to MEV bots and other market participants. **The Perfect Fee for Inclusion** On Ethereum, every transaction competes in a blind auction for blockspace. **Mispriced inclusion destroys value** either through unnecessary overpayment or costly execution failure.
* You don’t know the exact block composition * You don’t know competing orderflow * You don’t know builder behavior * You don’t know short-term demand spikes Nova minimizes execution uncertainty by dynamically optimising priority fees in real-time. Precision is the edge. **Live on Ethereum, Base, Arbitrum, and BSC.** To start using Nova, simply switch out your existing RPC endpoint to the following: `eth.novarpc.xyz` Please contact us at **** to start benefiting from MEV and gas refunds today. # Key Features Best Inclusion: Nova optimizes for latency, fee precision, and MEV protection to reduce inclusion uncertainty and deliver the strongest possible outcome for every transaction * **Industry Leading Refunds:** Real-time gas optimization means you won't overpay, whilst always meeting your inclusion goals. This means we can refund more on average than industry peers. * **MEV Protection and Capture:** Industry leading searchers are vetted to facilitate protection from front-running and sandwiching, and value capture from back-running opportunities (optional). * **Reduced Latency:** Private mempool operators typically act as middlemen, introducing an extra step in the transaction lifecycle between originators and block builders. Nova co-locates with a leading block builder to minimize inclusion latency. * **Enhanced Privacy:** Active monitoring of builder behaviour means transactions are only shared with Nova's trusted builder network. * **Avoid Failed Transactions:** Transactions are only included in a block if they do not revert, protecting users from costs associated with failed transactions (optional). * **Real-Time Analytics:** Easy to analyse statistics on revenue generated and inclusion. \ **Transaction API:** offers detailed status reports on transactions sent to Nova. For more information please see **Real-Time Analytics Dashboard:** # Why Use a Private Mempool There are two structural mechanisms through which transaction originators lose value on Ethereum:
1. **MEV:** Routing transactions to the public mempool transforms transactions into exploitable signals, meaning value is extracted by adversarial third parties before inclusion. This leads to: * Front-running * Back-running * Sandwich attacks * Increased slippage * Strategic manipulation\
2. Given lack of information, transaction originators commonly guess the price of blockspace. This leads to two forms of loss: * **Overpayment**: unnecessary transfer of surplus to validators/builders * **Underpayment**: delayed inclusion, failed execution, or opportunity loss In both cases, execution uncertainty destroys value. # Understanding MEV Blockspace as an Ordinal Commodity **Maximal Extractable Value (MEV) and Why Rank Matters** Traditional commodities are purely cardinal, where what matters is how much you have. Blockspace is both cardinal and ordinal: value depends on how much AND what rank you hold within a block. A trader whose transaction lands first captures arbitrage. A trader whose transaction lands second finds the opportunity gone. Same block, same commodity – radically different outcomes. This ordinal structure means MEV is not a bug or exploit; it emerges necessarily from the ordinal structure of blockspace, and the fact blockspace is capacity constrained. As long as rank carries value, there will be competition for rank.
# Private Auctions A very brief history of MEV on Ethereum Though MEV is intrinsically tied to the fundamental design of public, smart-contract-enabled blockchains, it can have negative externalities. Scenarios where multiple transactions are competing to be the first to modify a specific piece of the Ethereum state can degrade the user experience for everyday users, leading to network congestion, instability, and gas fee spikes. The solutions: * The Ethereum ecosystem adopted **private auctions** (see [Proposer Builder Seperation](https://ethereum.org/roadmap/pbs/)), essentially forcing the competition for blockspace rank offchain. This prevents failed transactions from ever hitting the public chain, keeping gas prices more stable for regular users. * To improve the experience of those transacting onchain, **order flow auctions (OFAs)** emerged as intermediaries between tx originators and block builders. OFAs were developed to protect users from front-running and sandwich attacks, and to capture back-running opportunities for those that created the value. # Fee Markets With the goal of further improving the user experience, Ethereum's fee market was overhauled with the [EIP-1559 upgrade](https://eips.ethereum.org/EIPS/eip-1559), replacing the first price auction system (highest bidder wins) with a system that encompasses the following: * **Base fee:** Algorithmically determined by the protocol itself, base fees represent the minimum fee for your transaction to be considered valid, and are burned upon inclusion. * **Priority Fee (Tip):** Users can optionally add a tip to incentivize validators to prioritize their transactions. This is especially relevant when the network is busy since block space is limited, or when a contentious state change exists. Whilst EIP-1559 attempted to improve the accuracy and predictability of Ethereum transaction fees, the capacity constraints of blockspace mean rank and inclusion latency remain dependant on tips users pay. For this reason, price discovery for blockspace remains inefficient... # Do I Qualify Generally speaking, the greater your role in originating a transaction, the greater your ability to recapture MEV and inherit priority fee refunds. For example: * **Wallets** can provide MEV protection and priority fee forecasting to users. * **Exchanges** can reduce priority fee outlays whilst ensuring timely internal transfers and user withdrawals. * **dApp** Front-Ends can protect users from MEV. * **RPC** providers can offer MEV protection alongside more specialist services. * **Oracle** providers can participate in the value (see [Chainlink Smart Value Recapture](https://docs.chain.link/data-feeds/svr-feeds#:~:text=Oracle%20Extractable%20Value%20\(OEV\)%20refers,inherently%20%22oracle%2Drelated%22.)) created by their price feeds. # How it Works * **Auction:** Nova routes transactions into a private bidding process where vetted searchers analyse the transaction and market for potential back-running opportunities. Searchers submit bids representing the value they are willing to return, and the highest bidder provides the optimal backrun.\ \ Nova bundles the user’s transaction with the winning backrun and submits the package to a trusted builder network, ensuring the user transaction, backrun, and associated refund are included atomically in the same block.\ \ This structure prevents harmful forms of MEV such as front-running and sandwich attacks, while allowing transaction originators to capture value generated by the signal their own transaction creates.\
* **Gas Recoveries:** OFA platforms must request gas recoveries from block builders. Without accurate insight into current block construction dynamics requests are simply estimates based on historical data. \ \ Nova minimizes execution uncertainty by dynamically optimising priority fees using real-time intelligence. # SOC 2 Compliance Sending transactions to a private mempool introduces additional counterparty risk and trust assumptions, making it vitally important to choose a trusted partner **Operational Excellence and Security** * The Nova team are SOC 2 Type II attested — ready to meet the rigorous security standards that today's most demanding enterprises require (please get in touch to request copy of the report).
**Stability and Alignment** * Nova is built for production-scale transaction execution, with sustainable, revenue-aligned economics aligning our success with yours, and enabling Nova to operate without the need for external funding.\ \ This operating model allows us to remain stable and reliable across volatile market cycles, reducing counterparty risk and providing the consistency that execution-critical infrastructure demands.
# Where is Nova Available * Ethereum Mainnet: `eth.novarpc.xyz`
* Base: `base.novarpc.xyz`
* BNB Smart Chain: `bsc.novarpc.xyz`
* Arbitrum: `arbitrum.novarpc.xyz` (coming soon) # How it Works on L2 The majority of L2 rollups rely on centralized, single party sequencers to order and execute transactions, thus eliminating the need for builders and a public mempool. Without visibility into pending transactions, MEV participants cannot effectively identify or execute front-running/sandwiching opportunities. However, back-running, which does not require seeing a transaction before it is executed remains, and may even be more likely to occur on L2 due to the cheaper gas which makes the point at which opportunities become profitable for searchers lower. **For this reason, Nova's searcher auction and back-running rebates run on L2.**\ \ To get started, simply switch out the existing sequencer endpoint to the Nova endpoint. Please contact us at **** to start benefiting from MEV protection and capture on L2 today. # Nova on Arbitrum Nova will route transactions through the Timeboost lane when Kairos is the Timeboost leader * **Timeboost:** The first wave of centralized sequencers, such as those operated within Base and Arbitrum ecosystems, ordered transactions based on a first come first served (FCFS), and via optional priority fees.\ \ However, downsides to FCFS emerged in the form of increased network congestion from searchers spamming the network to take advantage of MEV opportunities. In response, Offchain Labs developed Timeboost – a transaction ordering policy which combines an express lane and an offchain auction to protect users from MEV and reduce network spam, whilst preserving fast block times. * **Kairos:** Built by the same team behind Nova, Kairos is a native integration with Arbitrum Timeboost that offers a streamlined path for searchers and other participants to access express-lane blockspace—without directly engaging in each round-level Timeboost auction.
# RPC API Specification Requests to the RPC fall into one of two categories: ## Standard Ethereum JSON-RPC Methods in the Ethereum stable API behave like a typical Ethereum RPC endpoint. They follow standard request/response and work as expected with existing wallets and tooling. These are calls like `eth_estimateGas`, `eth_getBalance`, and `eth_chainId`. Many non-OFA RPC providers already document these, and it can be expected that we support the same things . ## Managed methods Managed methods are treated as workflow requests. Additional logic and constraints are applied to these methods, specific to bundle & transaction execution. These are calls like `eth_sendBundle`, and `eth_sendRawTransaction`. ### eth\_sendBundle {% content-ref url="/pages/dWxDfvJnCc6WEyqTR3xl" %} [eth\_sendBundle](/rpc-api-specification/eth_sendbundle) {% endcontent-ref %} ### eth\_sendRawTransaction {% content-ref url="/pages/H8xE4NEfvHAsjAw8zhDC" %} [eth\_sendRawTransaction](/rpc-api-specification/eth_sendrawtransaction) {% endcontent-ref %} ### eth\_getTransactionCount {% content-ref url="/pages/7fY84r6VZF21ovSXh9T4" %} [eth\_getTransactionCount](/rpc-api-specification/eth_gettransactioncount) {% endcontent-ref %} ### eth\_getTransactionByHash {% content-ref url="/pages/7UmrJDmLVaR5D1gQHkLw" %} [eth\_getTransactionByHash](/rpc-api-specification/eth_gettransactionbyhash) {% endcontent-ref %} # eth\_sendBundle ## POST / > \ > Submits a bundle of signed transactions to be executed atomically in a specific target block.\ > \ > \*\*Note\*\*\ > \- Acceptance does not mean the bundle will be included on-chain.\ > \- Inclusion depends on profitability, builder policies, and competing orderflow.
```json {"openapi":"3.1.0","info":{"title":"api-docs","version":"0.1.0"},"servers":[{"url":"https://eth.novarpc.xyz","description":"Mainnet"},{"url":"https://base.novarpc.xyz","description":"Base"}],"paths":{"/":{"post":{"tags":["RPC"],"description":"\nSubmits a bundle of signed transactions to be executed atomically in a specific target block.\n\n**Note**\n- Acceptance does not mean the bundle will be included on-chain.\n- Inclusion depends on profitability, builder policies, and competing orderflow.\n","operationId":"eth_sendBundle","parameters":[{"name":"api_key","in":"query","required":true,"schema":{"type":"string"}},{"name":"nomevrecovery","in":"query","description":"When present, disables MEV recovery (backrunning) for this request.","required":false,"schema":{"type":"boolean","default":false}},{"name":"norefund","in":"query","description":"When present, broadcasts this order without requesting a priority-fee refund, which\nincreases the likelihood of inclusion.","required":false,"schema":{"type":"boolean","default":false}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EthSendBundle"}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderHash"}}}}}}}},"components":{"schemas":{"EthSendBundle":{"type":"object","required":["txs"],"properties":{"allowBackruns":{"type":["boolean","null"],"description":"If `false`, MEV recovery (backrunning) is disabled for this bundle. Defaults to your account setting."},"blockNumber":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/BlockNumber","description":"The block number for which the bundle is valid, encoded as a hexadecimal string. Defaults to the current block."}]},"txs":{"type":"array","items":{"$ref":"#/components/schemas/Transaction"},"description":"An array of signed raw transactions to execute in an atomic bundle"}}},"BlockNumber":{"type":"string","pattern":"^0x[a-fA-F0-9]*$"},"Transaction":{"type":"string","description":"Raw transaction data, encoded as a hexadecimal string.","pattern":"^0x[a-fA-F0-9]*$"},"OrderHash":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$"}}}} ``` # eth\_sendRawTransaction ## POST / > \ > Submits a raw transaction (serialized + signed) for broadcasting to the network. Transaction data should be encoded as a hexadecimal string starting with \`0x\`.\ > \ > \*\*Notes\*\*\ > \- The node does not sign your transaction.\ > \- You typically sign locally using an external library like \*\*ethers.js\*\* or \*\*web3.js\*\*.\ > \ > \*\*EIP-4844\*\*\ > For blob transactions, the raw form must use the network format and include:\ > \- blobs\ > \- KZG commitments\ > \- KZG proofs
```json {"openapi":"3.1.0","info":{"title":"api-docs","version":"0.1.0"},"servers":[{"url":"https://eth.novarpc.xyz","description":"Mainnet"},{"url":"https://base.novarpc.xyz","description":"Base"}],"paths":{"/":{"post":{"tags":["RPC"],"description":"\nSubmits a raw transaction (serialized + signed) for broadcasting to the network. Transaction data should be encoded as a hexadecimal string starting with `0x`.\n\n**Notes**\n- The node does not sign your transaction.\n- You typically sign locally using an external library like **ethers.js** or **web3.js**.\n\n**EIP-4844**\nFor blob transactions, the raw form must use the network format and include:\n- blobs\n- KZG commitments\n- KZG proofs\n","operationId":"eth_sendRawTransaction","parameters":[{"name":"api_key","in":"query","required":true,"schema":{"type":"string"}},{"name":"noreverts","in":"query","description":"When present, enables revert protection: reverting transactions will not be included on-chain.","required":false,"schema":{"type":"boolean","default":false}},{"name":"nomevrecovery","in":"query","description":"When present, disables MEV recovery (backrunning) for this request.","required":false,"schema":{"type":"boolean","default":false}},{"name":"norefund","in":"query","description":"When present, broadcasts this order without requesting a priority-fee refund, which\nincreases the likelihood of inclusion.","required":false,"schema":{"type":"boolean","default":false}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Transaction"}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderHash"}}}}}}}},"components":{"schemas":{"Transaction":{"type":"string","description":"Raw transaction data, encoded as a hexadecimal string.","pattern":"^0x[a-fA-F0-9]*$"},"OrderHash":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$"}}}} ``` # eth\_getTransactionCount ## POST / > \ > Returns the number of transactions sent from a given address (account nonce).\ > \ > If the block tag is set to 'pending', then the RPC will intercept the call and return the highest nonce it has received.\ > \ > Note: the block tags 'safe' and 'finalized' are only availible on Ethereum mainnet.
```json {"openapi":"3.1.0","info":{"title":"api-docs","version":"0.1.0"},"servers":[{"url":"https://eth.novarpc.xyz","description":"Mainnet"},{"url":"https://base.novarpc.xyz","description":"Base"}],"paths":{"/":{"post":{"tags":["RPC"],"description":"\nReturns the number of transactions sent from a given address (account nonce).\n\nIf the block tag is set to 'pending', then the RPC will intercept the call and return the highest nonce it has received.\n\nNote: the block tags 'safe' and 'finalized' are only availible on Ethereum mainnet.\n","operationId":"eth_getTransactionCount","parameters":[{"name":"api_key","in":"query","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EthGetTransactionCount"}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderHash"}}}}}}}},"components":{"schemas":{"EthGetTransactionCount":{"type":"object","required":["address","block"],"properties":{"address":{"$ref":"#/components/schemas/Address","description":"The address of the account to get the transaction count for"},"block":{"$ref":"#/components/schemas/Block","description":"A block number as a hexadecimal string, or a block tag."}}},"Address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"Block":{"oneOf":[{"type":"object","required":["BlockHeight"],"properties":{"BlockHeight":{"$ref":"#/components/schemas/BlockHeight"}}},{"type":"object","required":["BlockTag"],"properties":{"BlockTag":{"$ref":"#/components/schemas/BlockTag"}}},{"type":"object","required":["BlockHash"],"properties":{"BlockHash":{"$ref":"#/components/schemas/BlockHash"}}}]},"BlockHeight":{"type":"string","pattern":"^0x([1-9a-f]+[0-9a-f]*|0)$"},"BlockTag":{"type":"string","enum":["latest","pending","earliest","finalized","safe"]},"BlockHash":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$"},"OrderHash":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$"}}}} ``` # eth\_getTransactionByHash ## POST / > \ > Returns details about a transaction for a given transaction hash.\ > \ > The RPC will check if the transaction is on chain, in the public mempool, or if it exists in our private mempool.\ > \ > If the transaction is returned from our private mempool the signatures (the \`v\`, \`r\`, \`s\` components) and gas price will be stripped from the result.
```json {"openapi":"3.1.0","info":{"title":"api-docs","version":"0.1.0"},"servers":[{"url":"https://eth.novarpc.xyz","description":"Mainnet"},{"url":"https://base.novarpc.xyz","description":"Base"}],"paths":{"/":{"post":{"tags":["RPC"],"description":"\nReturns details about a transaction for a given transaction hash.\n\nThe RPC will check if the transaction is on chain, in the public mempool, or if it exists in our private mempool.\n\nIf the transaction is returned from our private mempool the signatures (the `v`, `r`, `s` components) and gas price will be stripped from the result.\n","operationId":"eth_getTransactionByHash","parameters":[{"name":"api_key","in":"query","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderHash"}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TxEnvelope"}}}}}}}},"components":{"schemas":{"OrderHash":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$"},"TxEnvelope":{"oneOf":[{"type":"object","required":["Eip4844"],"properties":{"Eip4844":{"$ref":"#/components/schemas/Eip4844"}}},{"type":"object","required":["Eip1559"],"properties":{"Eip1559":{"$ref":"#/components/schemas/Eip1559"}}},{"type":"object","required":["Eip2930"],"properties":{"Eip2930":{"$ref":"#/components/schemas/Eip2930"}}},{"type":"object","required":["Legacy"],"properties":{"Legacy":{"$ref":"#/components/schemas/Legacy"}}}]},"Eip4844":{"type":"object","required":["type","nonce","to","gas","value","input","maxPriorityFeePerGas","maxFeePerGas","maxFeePerBlobGas","accessList","blobVersionedHashes","chainId","yParity","r","s"],"properties":{"accessList":{"type":"array","items":{"$ref":"#/components/schemas/EthAccessListItem"},"description":"EIP-2930 access list."},"blobVersionedHashes":{"type":"array","items":{"type":"string"},"description":"List of versioned blob hashes associated with the transaction's EIP-4844 data blobs."},"blockHash":{"type":["string","null"]},"blockNumber":{"type":["string","null"]},"chainId":{"type":"string","description":"Chain ID that this transaction is valid on."},"from":{"type":["string","null"]},"gas":{"type":"string","description":"Gas limit."},"hash":{"type":["string","null"]},"input":{"type":"string","description":"Calldata / initcode."},"maxFeePerBlobGas":{"type":"string","description":"The maximum total fee per gas the sender is willing to pay for blob gas in wei."},"maxFeePerGas":{"type":"string","description":"The maximum total fee per gas the sender is willing to pay (includes the network/base fee and miner/priority fee) in wei."},"maxPriorityFeePerGas":{"type":"string","description":"Maximum fee per gas the sender is willing to pay to miners in wei."},"nonce":{"type":"string","description":"Transaction nonce."},"r":{"type":"string"},"s":{"type":"string"},"to":{"type":"string","description":"Recipient address (non-null in this variant)."},"transactionIndex":{"type":["string","null"]},"type":{"type":"string","description":"Transaction type."},"value":{"type":"string","description":"Value transferred."},"yParity":{"type":"string","description":"The parity (0 for even, 1 for odd) of the y-value of the secp256k1 signature."}}},"EthAccessListItem":{"type":"object","description":"EIP-2930 access list entry: `(address, storageKeys[])`.","properties":{"address":{"type":["string","null"],"description":"Contract address."},"storageKeys":{"type":["array","null"],"items":{"type":"string"},"description":"Storage keys accessed by the transaction for this address."}}},"Eip1559":{"type":"object","required":["type","nonce","gas","value","input","maxPriorityFeePerGas","maxFeePerGas","gasPrice","accessList","chainId","yParity","r","s"],"properties":{"accessList":{"type":"array","items":{"$ref":"#/components/schemas/EthAccessListItem"},"description":"EIP-2930 access list."},"blockHash":{"type":["string","null"]},"blockNumber":{"type":["string","null"]},"chainId":{"type":"string","description":"Chain ID that this transaction is valid on."},"from":{"type":["string","null"]},"gas":{"type":"string"},"gasPrice":{"type":"string","description":"The effective gas price paid by the sender in wei.\nDeprecated in the spec text (prefer effectiveGasPrice in receipt)."},"hash":{"type":["string","null"]},"input":{"type":"string"},"maxFeePerGas":{"type":"string","description":"The maximum total fee per gas the sender is willing to pay (includes the network/base fee and miner/priority fee) in wei."},"maxPriorityFeePerGas":{"type":"string","description":"Maximum fee per gas the sender is willing to pay to miners in wei."},"nonce":{"type":"string"},"r":{"type":"string"},"s":{"type":"string"},"to":{"type":["string","null"],"description":"Recipient address (null for contract creation)."},"transactionIndex":{"type":["string","null"]},"type":{"type":"string"},"v":{"type":["string","null"],"description":"For backwards compatibility, `v` is optionally provided as an alternative to `yParity`.\nDeprecated in the spec text."},"value":{"type":"string"},"yParity":{"type":"string","description":"The parity (0 for even, 1 for odd) of the y-value of the secp256k1 signature."}}},"Eip2930":{"type":"object","required":["type","nonce","gas","value","input","gasPrice","accessList","chainId","yParity","r","s"],"properties":{"accessList":{"type":"array","items":{"$ref":"#/components/schemas/EthAccessListItem"},"description":"EIP-2930 access list."},"blockHash":{"type":["string","null"]},"blockNumber":{"type":["string","null"]},"chainId":{"type":"string","description":"Chain ID that this transaction is valid on."},"from":{"type":["string","null"]},"gas":{"type":"string"},"gasPrice":{"type":"string","description":"The gas price willing to be paid by the sender in wei."},"hash":{"type":["string","null"]},"input":{"type":"string"},"nonce":{"type":"string"},"r":{"type":"string"},"s":{"type":"string"},"to":{"type":["string","null"],"description":"Recipient address (null for contract creation)."},"transactionIndex":{"type":["string","null"]},"type":{"type":"string"},"v":{"type":["string","null"],"description":"For backwards compatibility, `v` is optionally provided as an alternative to `yParity`.\nDeprecated in the spec text."},"value":{"type":"string"},"yParity":{"type":"string","description":"The parity (0 for even, 1 for odd) of the y-value of the secp256k1 signature."}}},"Legacy":{"type":"object","required":["type","nonce","gas","value","input","gasPrice","v","r","s"],"properties":{"blockHash":{"type":["string","null"]},"blockNumber":{"type":["string","null"]},"chainId":{"type":["string","null"],"description":"Chain ID that this transaction is valid on."},"from":{"type":["string","null"]},"gas":{"type":"string"},"gasPrice":{"type":"string","description":"The gas price willing to be paid by the sender in wei."},"hash":{"type":["string","null"]},"input":{"type":"string"},"nonce":{"type":"string"},"r":{"type":"string"},"s":{"type":"string"},"to":{"type":["string","null"],"description":"Recipient address (null for contract creation)."},"transactionIndex":{"type":["string","null"]},"type":{"type":"string"},"v":{"type":"string"},"value":{"type":"string"}}}}}} ``` # Data API ## Endpoint & Authentication ``` https://api.novarpc.xyz/v1/{chain}/ ``` Replace `{chain}` with one of: * `eth` (ETH mainnet) * `base` (Base mainnet) ### Authentication To authenticate your requests, include your API key in the `Authorization` header of each request. The API key is a unique string assigned to you and must be included in the following format: ``` Authorization: Bearer ``` # /account ## POST /v1/{chain}/account > \ > Enable or disable processing of your RPC requests.\ > \ > Set \`enabled\` to \`false\` to pause processing. Set \`enabled\` to \`true\` to resume.\ > \ > Omit \`enabled\` to check the current status without making any change.\ > \ > Changes propagate within \~60 seconds.
```json {"openapi":"3.1.0","info":{"title":"api-docs","version":"0.1.0"},"servers":[{"url":"https://api.novarpc.xyz"}],"security":[{"ApiKeyQuery":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Your API key"}},"schemas":{"Chain":{"type":"string","enum":["eth","base"]},"UpdateAccountRequest":{"type":"object","properties":{"enabled":{"type":["boolean","null"]}}},"UpdateAccountResponse":{"type":"object","required":["enabled"],"properties":{"enabled":{"type":"boolean"}}}}},"paths":{"/v1/{chain}/account":{"post":{"tags":["Reporting API"],"description":"\nEnable or disable processing of your RPC requests.\n\nSet `enabled` to `false` to pause processing. Set `enabled` to `true` to resume.\n\nOmit `enabled` to check the current status without making any change.\n\nChanges propagate within ~60 seconds.\n","operationId":"update_account","parameters":[{"name":"chain","in":"path","description":"Chain to query for","required":true,"schema":{"$ref":"#/components/schemas/Chain"}},{"name":"api_key","in":"query","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAccountRequest"}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAccountResponse"}}}},"401":{"description":"Invalid or missing API key"},"404":{"description":"Chain not supported"}}}}}} ``` # /order ## POST /v1/{chain}/order > \ > Get details for a specific order, including refund info and if it was mined.\ > \ > \### Compression\ > \ > Optional HTTP compression is supported.\ > \ > \*\*Request\*\*: Clients may compress the JSON request body and specify the encoding via the \`Content-Encoding\` header.\ > \ > \*\*Response\*\*: Clients may request responses to be compressed by specifying encodings via the \`Accept-Encoding\` header.\ > \ > Supported encodings:\ > \- \`zstd\`\ > \- \`gzip\`\ > \- \`br\` (Brotli)
```json {"openapi":"3.1.0","info":{"title":"api-docs","version":"0.1.0"},"servers":[{"url":"https://api.novarpc.xyz"}],"security":[{"ApiKeyQuery":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Your API key"}},"schemas":{"Chain":{"type":"string","enum":["eth","base"]},"OrderRequest":{"type":"object","required":["order_hash"],"properties":{"order_hash":{"type":"string","pattern":"0[xX][0-9a-fA-F]+"}}},"OrderDetail":{"type":"object","required":["order_hash","order_type","received_auction_bids","unique_searchers","received_block","received_at","refunds","tx_hashes","prio_fee_paid","mev_backruns","auction_bids","status"],"properties":{"auction_bids":{"type":"array","items":{"$ref":"#/components/schemas/AuctionBidEntry"},"description":"Successful simulation bids for this order, ordered chronologically by time received"},"dropped":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/DropInfo","description":"The reason the OFA dropped this order, if any"}]},"mev_backruns":{"type":"array","items":{"$ref":"#/components/schemas/B256"},"description":"If this order was successfully backrun by searchers, this list will contain each of those backrun orders"},"mined_block":{"type":["integer","null"],"format":"int64","description":"The block that included this order; `null` if it has not been mined."},"order_hash":{"type":"string"},"order_type":{"type":"string"},"prio_fee_paid":{"type":"number","format":"double","description":"The prio fee paid on chain"},"received_at":{"type":"string","format":"date-time"},"received_auction_bids":{"type":"integer","format":"int64"},"received_block":{"type":"integer","format":"int64"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/RefundInfo"}},"status":{"$ref":"#/components/schemas/OrderStatus","description":"The status of this order"},"tag":{"type":["string","null"]},"tx_hashes":{"type":"array","items":{"$ref":"#/components/schemas/B256"},"description":"If this order is a bundle, this is an ordered array containing its transactions. If it is a transaction, this is a single element array\ncontaining its hash"},"unique_searchers":{"type":"integer","format":"int64"}}},"AuctionBidEntry":{"type":"object","required":["searcher","amount","received_at"],"properties":{"amount":{"type":"number","format":"double"},"received_at":{"type":"string","format":"date-time"},"searcher":{"type":"integer","description":"Privacy-preserving, one-based searcher identifier, stable within this order's bid sequence.","minimum":1}}},"DropInfo":{"type":"object","required":["reason"],"properties":{"block_number":{"type":["integer","null"],"format":"int64","description":"The block number at which this order was simulated and dropped. Only present for `SimFailure` drops"},"reason":{"type":"string","description":"Why the order was dropped. Possible values:\n- `Mempool`: the transaction was detected in the public mempool\n- `Mined`: the transaction was already included on-chain before it could be processed\n- `SimFailure: `: the order failed simulation; the reason text follows the colon"}}},"B256":{"type":"string","pattern":"^0x[0-9a-fA-F]{64}$"},"RefundInfo":{"type":"object","required":["refunded_amount","refund_payout_type","is_backrun"],"properties":{"is_backrun":{"type":"boolean"},"payout_tx_hash":{"type":"string","description":"Transaction sent by Nova to pay this refund."},"refund_payout_type":{"type":"string"},"refunded_amount":{"type":"string"}}},"OrderStatus":{"type":"string","enum":["pending","confirmed","dropped","expired","replaced"]}}},"paths":{"/v1/{chain}/order":{"post":{"tags":["Reporting API"],"description":" \nGet details for a specific order, including refund info and if it was mined.\n\n### Compression\n\nOptional HTTP compression is supported.\n\n**Request**: Clients may compress the JSON request body and specify the encoding via the `Content-Encoding` header.\n\n**Response**: Clients may request responses to be compressed by specifying encodings via the `Accept-Encoding` header.\n\nSupported encodings:\n- `zstd`\n- `gzip`\n- `br` (Brotli)\n","operationId":"order","parameters":[{"name":"chain","in":"path","description":"Chain to query for","required":true,"schema":{"$ref":"#/components/schemas/Chain"}},{"name":"api_key","in":"query","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderRequest"}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderDetail"}}}}}}}}} ``` # /orders ## POST /v1/{chain}/orders > The same statistics from \`/orders\_stats\` as well as all orders over that timeframe. The time is inclusive of start\_time and exclusive of end\_time, and is capped at a maximum window of 1 day by default. Repeatedly calling with a high limit may cause rate limiting. ```json {"openapi":"3.1.0","info":{"title":"api-docs","version":"0.1.0"},"servers":[{"url":"https://api.novarpc.xyz"}],"security":[{"ApiKeyQuery":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Your API key"}},"schemas":{"Chain":{"type":"string","enum":["eth","base"]},"OrderStatsRequest":{"type":"object","required":["start_time","end_time"],"properties":{"end_time":{"type":"string","format":"date-time"},"include_unmined":{"type":"boolean","description":"If true, all orders are returned. If false, only mined orders are returned."},"limit":{"type":["integer","null"],"description":"Maximum number of orders to aggregate.","default":10000,"minimum":0},"offset":{"type":"integer","minimum":0},"start_time":{"type":"string","format":"date-time"}}},"OrderStatsWithOrders":{"type":"object","required":["stats","orders"],"properties":{"orders":{"type":"array","items":{"$ref":"#/components/schemas/OrderDetail"}},"stats":{"$ref":"#/components/schemas/OrderStats"}}},"OrderDetail":{"type":"object","required":["order_hash","order_type","received_auction_bids","unique_searchers","received_block","received_at","refunds","tx_hashes","prio_fee_paid","mev_backruns","auction_bids","status"],"properties":{"auction_bids":{"type":"array","items":{"$ref":"#/components/schemas/AuctionBidEntry"},"description":"Successful simulation bids for this order, ordered chronologically by time received"},"dropped":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/DropInfo","description":"The reason the OFA dropped this order, if any"}]},"mev_backruns":{"type":"array","items":{"$ref":"#/components/schemas/B256"},"description":"If this order was successfully backrun by searchers, this list will contain each of those backrun orders"},"mined_block":{"type":["integer","null"],"format":"int64","description":"The block that included this order; `null` if it has not been mined."},"order_hash":{"type":"string"},"order_type":{"type":"string"},"prio_fee_paid":{"type":"number","format":"double","description":"The prio fee paid on chain"},"received_at":{"type":"string","format":"date-time"},"received_auction_bids":{"type":"integer","format":"int64"},"received_block":{"type":"integer","format":"int64"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/RefundInfo"}},"status":{"$ref":"#/components/schemas/OrderStatus","description":"The status of this order"},"tag":{"type":["string","null"]},"tx_hashes":{"type":"array","items":{"$ref":"#/components/schemas/B256"},"description":"If this order is a bundle, this is an ordered array containing its transactions. If it is a transaction, this is a single element array\ncontaining its hash"},"unique_searchers":{"type":"integer","format":"int64"}}},"AuctionBidEntry":{"type":"object","required":["searcher","amount","received_at"],"properties":{"amount":{"type":"number","format":"double"},"received_at":{"type":"string","format":"date-time"},"searcher":{"type":"integer","description":"Privacy-preserving, one-based searcher identifier, stable within this order's bid sequence.","minimum":1}}},"DropInfo":{"type":"object","required":["reason"],"properties":{"block_number":{"type":["integer","null"],"format":"int64","description":"The block number at which this order was simulated and dropped. Only present for `SimFailure` drops"},"reason":{"type":"string","description":"Why the order was dropped. Possible values:\n- `Mempool`: the transaction was detected in the public mempool\n- `Mined`: the transaction was already included on-chain before it could be processed\n- `SimFailure: `: the order failed simulation; the reason text follows the colon"}}},"B256":{"type":"string","pattern":"^0x[0-9a-fA-F]{64}$"},"RefundInfo":{"type":"object","required":["refunded_amount","refund_payout_type","is_backrun"],"properties":{"is_backrun":{"type":"boolean"},"payout_tx_hash":{"type":"string","description":"Transaction sent by Nova to pay this refund."},"refund_payout_type":{"type":"string"},"refunded_amount":{"type":"string"}}},"OrderStatus":{"type":"string","enum":["pending","confirmed","dropped","expired","replaced"]},"OrderStats":{"type":"object","required":["total_orders","included_orders","inclusion_rate","block_0_inclusion_rate","block_1_inclusion_rate","total_refunds_received","mev_refunds","priority_fee_refunds","priority_fees_paid"],"properties":{"block_0_inclusion_rate":{"type":"number","format":"double","description":"Percentage of eligible txs that were included on the same block as they arrived"},"block_1_inclusion_rate":{"type":"number","format":"double","description":"Percentage of eligible txs that were included on the next block after they arrived"},"included_orders":{"type":"integer","format":"int64","description":"Total number of mined orders"},"inclusion_rate":{"type":"number","format":"double","description":"Ratio of included orders / total orders"},"mev_refunds":{"type":"number","format":"double","description":"Captured MEV generated by these orders"},"priority_fee_refunds":{"type":"number","format":"double","description":"Total refunded priority fees"},"priority_fees_paid":{"type":"number","format":"double","description":"Total fees paid (priority fees + block fee recipient payments) for orders that generated a priority fee based refund"},"total_orders":{"type":"integer","format":"int64","description":"Total number of received orders"},"total_refunds_received":{"type":"number","format":"double","description":"Equal to mev_refunds + priority_fee_refunds"}}}}},"paths":{"/v1/{chain}/orders":{"post":{"tags":["Reporting API"],"description":"The same statistics from `/orders_stats` as well as all orders over that timeframe. The time is inclusive of start_time and exclusive of end_time, and is capped at a maximum window of 1 day by default. Repeatedly calling with a high limit may cause rate limiting.","operationId":"orders","parameters":[{"name":"chain","in":"path","description":"Chain to query for","required":true,"schema":{"$ref":"#/components/schemas/Chain"}},{"name":"api_key","in":"query","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderStatsRequest"}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderStatsWithOrders"}}}}}}}}} ``` # /orders\_stats ## POST /v1/{chain}/order\_stats > Aggregated order statistics over a given timeframe. The time is inclusive of start\_time and exclusive of end\_time, and is capped at a maximum window of 1 day by default. Repeatedly calling with a high limit may cause rate limiting. ```json {"openapi":"3.1.0","info":{"title":"api-docs","version":"0.1.0"},"servers":[{"url":"https://api.novarpc.xyz"}],"security":[{"ApiKeyQuery":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Your API key"}},"schemas":{"Chain":{"type":"string","enum":["eth","base"]},"OrderStatsRequest":{"type":"object","required":["start_time","end_time"],"properties":{"end_time":{"type":"string","format":"date-time"},"include_unmined":{"type":"boolean","description":"If true, all orders are returned. If false, only mined orders are returned."},"limit":{"type":["integer","null"],"description":"Maximum number of orders to aggregate.","default":10000,"minimum":0},"offset":{"type":"integer","minimum":0},"start_time":{"type":"string","format":"date-time"}}},"OrderStats":{"type":"object","required":["total_orders","included_orders","inclusion_rate","block_0_inclusion_rate","block_1_inclusion_rate","total_refunds_received","mev_refunds","priority_fee_refunds","priority_fees_paid"],"properties":{"block_0_inclusion_rate":{"type":"number","format":"double","description":"Percentage of eligible txs that were included on the same block as they arrived"},"block_1_inclusion_rate":{"type":"number","format":"double","description":"Percentage of eligible txs that were included on the next block after they arrived"},"included_orders":{"type":"integer","format":"int64","description":"Total number of mined orders"},"inclusion_rate":{"type":"number","format":"double","description":"Ratio of included orders / total orders"},"mev_refunds":{"type":"number","format":"double","description":"Captured MEV generated by these orders"},"priority_fee_refunds":{"type":"number","format":"double","description":"Total refunded priority fees"},"priority_fees_paid":{"type":"number","format":"double","description":"Total fees paid (priority fees + block fee recipient payments) for orders that generated a priority fee based refund"},"total_orders":{"type":"integer","format":"int64","description":"Total number of received orders"},"total_refunds_received":{"type":"number","format":"double","description":"Equal to mev_refunds + priority_fee_refunds"}}}}},"paths":{"/v1/{chain}/order_stats":{"post":{"tags":["Reporting API"],"description":"Aggregated order statistics over a given timeframe. The time is inclusive of start_time and exclusive of end_time, and is capped at a maximum window of 1 day by default. Repeatedly calling with a high limit may cause rate limiting.","operationId":"order_stats","parameters":[{"name":"chain","in":"path","description":"Chain to query for","required":true,"schema":{"$ref":"#/components/schemas/Chain"}},{"name":"api_key","in":"query","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderStatsRequest"}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderStats"}}}}}}}}} ``` # /auction\_bids ## POST /v1/{chain}/auction\_bids > \ > Get auction bids for a specific block number\ > \ > \### Compression\ > \ > Optional HTTP compression is supported.\ > \ > \*\*Request\*\*: Clients may compress the JSON request body and specify the encoding via the \`Content-Encoding\` header.\ > \ > \*\*Response\*\*: Clients may request responses to be compressed by specifying encodings via the \`Accept-Encoding\` header.\ > \ > Supported encodings:\ > \- \`zstd\`\ > \- \`gzip\`\ > \- \`br\` (Brotli)
```json {"openapi":"3.1.0","info":{"title":"api-docs","version":"0.1.0"},"servers":[{"url":"https://api.novarpc.xyz"}],"security":[{"ApiKeyQuery":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Your API key"}},"schemas":{"Chain":{"type":"string","enum":["eth","base"]},"AuctionBidRequest":{"type":"object","required":["block_number"],"properties":{"block_number":{"type":"integer","format":"int64","minimum":0}}},"AuctionBids":{"type":"object","required":["bids"],"properties":{"bids":{"type":"array","items":{"$ref":"#/components/schemas/AuctionBidDetail"}}}},"AuctionBidDetail":{"type":"object","required":["block_number","sim_success","builder_payment","received_at","simulated_at"],"properties":{"block_number":{"type":"integer","format":"int64"},"builder_payment":{"type":"number","format":"double"},"received_at":{"type":"string"},"sim_error":{"type":["string","null"]},"sim_success":{"type":"boolean"},"simulated_at":{"type":"string"}}}}},"paths":{"/v1/{chain}/auction_bids":{"post":{"tags":["Reporting API"],"description":"\nGet auction bids for a specific block number\n \n### Compression\n\nOptional HTTP compression is supported.\n\n**Request**: Clients may compress the JSON request body and specify the encoding via the `Content-Encoding` header.\n\n**Response**: Clients may request responses to be compressed by specifying encodings via the `Accept-Encoding` header.\n\nSupported encodings:\n- `zstd`\n- `gzip`\n- `br` (Brotli)\n","operationId":"auction_bids","parameters":[{"name":"chain","in":"path","description":"Chain to query for","required":true,"schema":{"$ref":"#/components/schemas/Chain"}},{"name":"api_key","in":"query","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuctionBidRequest"}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuctionBids"}}}}}}}}} ``` # /refunds ## POST /v1/{chain}/refunds > \ > Get refunds for your account. Filter by time range, block range, and payout status. Supports pagination with limit and offset.\ > \ > \### Compression\ > \ > Optional HTTP compression is supported.\ > \ > \*\*Request\*\*: Clients may compress the JSON request body and specify the encoding via the \`Content-Encoding\` header.\ > \ > \*\*Response\*\*: Clients may request responses to be compressed by specifying encodings via the \`Accept-Encoding\` header.\ > \ > Supported encodings:\ > \- \`zstd\`\ > \- \`gzip\`\ > \- \`br\` (Brotli)
```json {"openapi":"3.1.0","info":{"title":"api-docs","version":"0.1.0"},"servers":[{"url":"https://api.novarpc.xyz"}],"security":[{"ApiKeyQuery":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Your API key"}},"schemas":{"Chain":{"type":"string","enum":["eth","base"]},"RefundsRequest":{"type":"object","properties":{"end_block":{"type":["integer","null"],"format":"int64","minimum":0},"end_time":{"type":["string","null"],"format":"date-time"},"limit":{"type":"integer","default":100000,"minimum":0},"offset":{"type":"integer","minimum":0},"payout_status":{"type":["string","null"]},"start_block":{"type":["integer","null"],"format":"int64","minimum":0},"start_time":{"type":["string","null"],"format":"date-time"}}},"RefundsResponse":{"type":"object","required":["refunds","count"],"properties":{"count":{"type":"integer","minimum":0},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/RefundDetail"}}}},"RefundDetail":{"type":"object","required":["order_hash","block_number","refunded_amount","payout_status","is_mev_refund","timestamp"],"properties":{"block_number":{"type":"integer","format":"int64"},"is_mev_refund":{"type":"boolean"},"order_hash":{"type":"string"},"paid_at":{"type":["string","null"]},"payout_status":{"type":"string"},"payout_tx_hash":{"type":"string","description":"Transaction sent by Nova to pay this refund."},"refunded_amount":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}}}},"paths":{"/v1/{chain}/refunds":{"post":{"tags":["Reporting API"],"description":"\nGet refunds for your account. Filter by time range, block range, and payout status. Supports pagination with limit and offset.\n\n### Compression\n\nOptional HTTP compression is supported.\n\n**Request**: Clients may compress the JSON request body and specify the encoding via the `Content-Encoding` header.\n\n**Response**: Clients may request responses to be compressed by specifying encodings via the `Accept-Encoding` header.\n\nSupported encodings:\n- `zstd`\n- `gzip`\n- `br` (Brotli)\n","operationId":"refunds","parameters":[{"name":"chain","in":"path","description":"Chain to query for","required":true,"schema":{"$ref":"#/components/schemas/Chain"}},{"name":"api_key","in":"query","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundsRequest"}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundsResponse"}}}}}}}}} ``` # /refunds\_stats ## POST /v1/{chain}/refunds\_stats > \ > Get aggregated refund statistics for your account. Returns totals and counts broken down by payout status and refund type.\ > \ > \### Compression\ > \ > Optional HTTP compression is supported.\ > \ > \*\*Request\*\*: Clients may compress the JSON request body and specify the encoding via the \`Content-Encoding\` header.\ > \ > \*\*Response\*\*: Clients may request responses to be compressed by specifying encodings via the \`Accept-Encoding\` header.\ > \ > Supported encodings:\ > \- \`zstd\`\ > \- \`gzip\`\ > \- \`br\` (Brotli)
```json {"openapi":"3.1.0","info":{"title":"api-docs","version":"0.1.0"},"servers":[{"url":"https://api.novarpc.xyz"}],"security":[{"ApiKeyQuery":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Your API key"}},"schemas":{"Chain":{"type":"string","enum":["eth","base"]},"RefundStatsRequest":{"type":"object","properties":{"end_block":{"type":["integer","null"],"format":"int64","minimum":0},"end_time":{"type":["string","null"],"format":"date-time"},"start_block":{"type":["integer","null"],"format":"int64","minimum":0},"start_time":{"type":["string","null"],"format":"date-time"}}},"RefundStatsResponse":{"type":"object","required":["total_refund_amount","pending_refund_amount","paid_amount","mev_refund_amount","priority_fee_refund_amount","total_refund_count","pending_count","paid_count"],"properties":{"mev_refund_amount":{"type":"string"},"paid_amount":{"type":"string"},"paid_count":{"type":"integer","format":"int64"},"pending_count":{"type":"integer","format":"int64"},"pending_refund_amount":{"type":"string"},"priority_fee_refund_amount":{"type":"string"},"total_refund_amount":{"type":"string"},"total_refund_count":{"type":"integer","format":"int64"}}}}},"paths":{"/v1/{chain}/refunds_stats":{"post":{"tags":["Reporting API"],"description":"\nGet aggregated refund statistics for your account. Returns totals and counts broken down by payout status and refund type.\n\n### Compression\n\nOptional HTTP compression is supported.\n\n**Request**: Clients may compress the JSON request body and specify the encoding via the `Content-Encoding` header.\n\n**Response**: Clients may request responses to be compressed by specifying encodings via the `Accept-Encoding` header.\n\nSupported encodings:\n- `zstd`\n- `gzip`\n- `br` (Brotli)\n","operationId":"refunds_stats","parameters":[{"name":"chain","in":"path","description":"Chain to query for","required":true,"schema":{"$ref":"#/components/schemas/Chain"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundStatsRequest"}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundStatsResponse"}}}}}}}}} ``` # Searchers Qualifying transactions & bundles can be sent to searchers, sharing the resulting profits. Here you will find further details on how to establish a WebSocket connection to receive originator transactions and information on how to send your bundles back to our rpc endpoint. ## Integration Please reach out to get set up with an API key. # Ethereum This API provides protected pending transactions and bundles on Ethereum mainnet and accepts backrun bundles over the same WebSocket connection. The model is similar to Base but without flashblocks; latency still matters, but auctions are not sub-200ms. An API key is required for access. *** #### WebSocket Connection Connect using your API key: ```html wss://eth.novarpc.xyz/ws/v1/ ``` The protocol is JSON-RPC 2.0 over WebSocket. Clients must reconnect and resubscribe if the connection drops. Subscriptions are not persisted. *** #### Subscribing to Flow After connecting, send `eth_subscribe` to receive qualifying flow. You may subscribe to transactions, bundles, or both. Pending transactions: ```json { "jsonrpc": "2.0", "id": 1, "method": "eth_subscribe", "params": ["nova_partialPendingTransactions"] } ``` Pending bundles: ```json { "jsonrpc": "2.0", "id": 2, "method": "eth_subscribe", "params": ["nova_partialPendingBundles"] } ``` Each subscription returns a subscription ID: ```json { "jsonrpc": "2.0", "id": 1, "result": "0xa04fcb2de702f3bcd205ce666b7d5232" } ``` This ID is used client-side to match incoming messages to the corresponding subscription. *** #### Receiving Data Subscribed data is delivered via `eth_subscription` messages. For individual transactions, the `result` field contains a single transaction object: ```json { "jsonrpc": "2.0", "method": "eth_subscription", "params": { "subscription": "0xa04fcb2de702f3bcd205ce666b7d5232", "result": { "chainId": "0x1", "from": "0xcba40bd88d70ec7b31a898e1a5d1cffde91069f2", "to": "0xa44f26477bd3460103310395f4e3b713d4c9e5d6", "hash": "0x04f2103bed46aef0edf4ece05c5a43a72df127315b097e6bc1615ac8d8cd59f9", "value": "0x18fae27693b40000", "gas": "0x5a3c", "maxPriorityFeePerGas": "0x216744fd", "maxFeePerGas": "0x4b04cc44a", "nonce": "0x1ca", "type": "0x2", "data": "0x", "accessList": [] } } } ``` For bundles, the `result` field is an array of one or more transactions: ```json { "jsonrpc": "2.0", "method": "eth_subscription", "params": { "subscription": "0xc06fe452246374c64932164bbc045530", "result": [ { "...tx1 fields..." }, { "...tx2 fields..." } ] } } ``` The only structural difference between transactions and bundles is that bundles return an array. In both cases, the `hash` field identifies the originator transaction or bundle that must be referenced when backrunning. *** #### Sending Bundles Backrun bundles must be submitted over this WebSocket connection. Sending them to a standard HTTP `eth_sendBundle` endpoint will not work. ```json { "jsonrpc": "2.0", "id": 3, "method": "eth_sendBundle", "params": [ { "txs": [ "0xOriginatorHash", "0xRawSignedTransaction" ] } ] } ``` The `txs` array must be ordered. The first element is always the hash of the pending transaction or bundle you are backrunning. Subsequent elements are your signed transactions in raw hex form. When backrunning a received bundle, each transaction will appear with a generated bundle hash. Include that generated hash only once as the first element in `txs`. # Oracle Extractable Value ### Oracles Oracles let smart contracts access off-chain data. In practice, an oracle updates on-chain state by submitting a regular transaction, which means any OEV created by that update can be auctioned in much the same way as MEV around regular transactions. This can be valuable to searchers. For example, if a lending protocol updates its internal ETH/USD price, that price change may create profitable opportunities to arbitrage ### OEV Auctions Nova runs auctions for oracle update transactions. Functionally, this is similar to a standard MEV auction on Ethereum mainnet. The main difference is how backruns are sent to block builders. Instead of being submitted as an atomic bundle with the oracle update transaction, Nova may send backruns to the builder as standalone transactions. This is sometimes done to maximize the chance of inclusion, since some builders apply special handling or restrictions to oracle update transactions. ### Participating in OEV Auctions If you are already connected to Nova's searcher WebSocket, congratulations! There is nothing else you need to do. Oracle transactions and their backruns are sent via the same WebSocket as regular flow. Your backrun bundle must still reference the originating oracle transaction hash, just like any other auction. Nova takes care of how the backrun is ultimately delivered to the builder. # Base Searchers can connect to a WebSocket feed of private pending transactions on Base, allowing them to submit backrun bundles into a short, competitive auction window. An API key is required. Keys authenticate the WebSocket connection and may be rate-limited or revoked if rules are violated. *** #### Auction Mechanics Each eligible transaction opens a short auction window (up to \~100ms). The unsigned transaction is sent via WebSocket to searchers, and searchers may send one or more bids to win the right to backrun the transaction. At auction end, the highest-paying searcher is sent the raw signed transaction and may broadcast it, along with their backrun, directly to the sequencer. After some time, Nova also broadcasts the transaction and backrun to the sequencer, guaranteeing inclusion. Latency is critical, and colocation in AWS us-east-1 is strongly recommended.
*** #### Refund Rules Searchers must return at least 75% of realized profit to the refund address: ```rust 0xfbFAF450E7e739f11584D9Db1dAfd1E7a77099fb ``` An example of this can be seen [here](https://basescan.org/tx/0x7b71a6fff22c9b436cf41b469dbd99aecfefa60978030d3c30cfc2cf8cd93670). This refund must be an explicit ETH transfer included in the backrun transaction itself. Profit is evaluated per bundle based on on-chain execution. Any form of sandwiching against protected transactions results in an immediate ban. *** #### Monitoring and Enforcement The system continuously monitors: * Sandwich behavior * Profit share compliance (≥ 75%) * Revert rates, especially during competitive auctions * Latency and submission patterns Violations may result in reduced flow, artificial websocket delays, or a permanent ban, depending on severity and persistence. *** #### WebSocket Connection Connect using your API key: ```html wss://base.novarpc.xyz/ws/v1/ ``` The protocol uses JSON-RPC 2.0 over WebSocket. If the connection drops, clients must reconnect and resubscribe. No state is preserved across reconnects. *** #### Transaction Subscription After connecting, you must explicitly subscribe to receive transactions: ```json { "jsonrpc": "2.0", "id": 1, "method": "eth_subscribe", "params": ["nova_partialPendingTransactions"] } ``` The stream emits pending transactions eligible for backruns. Messages are delivered in the order they arrive at the server. No ordering or completeness guarantees are provided beyond that. Responses contain individual transactions with signature fields stripped: ```json { "jsonrpc": "2.0", "method": "eth_subscription", "params": { "subscription": "0xa04fcb2de702f3bcd205ce666b7d5232", "result": { "chainId": "0x2105", "from": "0xcba40bd88d70ec7b31a898e1a5d1cffde91069f2", "to": "0xa44f26477bd3460103310395f4e3b713d4c9e5d6", "hash": "0x04f2103bed46aef0edf4ece05c5a43a72df127315b097e6bc1615ac8d8cd59f9", "value": "0x18fae27693b40000", "gas": "0x5a3c", "maxPriorityFeePerGas": "0x216744fd", "maxFeePerGas": "0x4b04cc44a", "nonce": "0x1ca", "type": "0x2", "data": "0x", "accessList": [] } } } ``` If your bid wins the auction, you will receive the signed raw transaction bytes ```json { "jsonrpc": "2.0", "method": "eth_subscription", "params": { "subscription": "0xa04fcb2de702f3bcd205ce666b7d5232", "result": { ... "rawTx": "0x..." } } } ``` *** #### Submitting Bids Bids are submitted over the same WebSocket connection using eth\_sendBundle: ```json { "jsonrpc": "2.0", "id": 2, "method": "eth_sendBundle", "params": [ { "txs": [ "0xTargetTransactionHash", "0xRawBackrunTransaction" ], "bid": 5000000000, "replacementUuid": "550e8400-e29b-41d4-a716-446655440000" } ] } ``` * `txs` - an array where the first element is the target transaction hash (as received in the auction notification), and the second element\ is your signed backrun transaction in raw hex form. Only one backrun transaction is supported per bundle. * `bid` - your bid amount in wei. This is used to rank backruns during the auction. * `replacementUuid` - optional. If provided, any previous bid with the same UUID will be replaced, allowing you to update your bid during\ the auction window. {% hint style="warning" %} Note: Auctions may extend beyond the current flashblock. If the auction window spans a flashblock boundary, the winning backrun will be included in the next flashblock. {% endhint %}