eth_backrun

Given a user transaction description, returns ready-to-use backrun calldata that the partner composes into the user transaction so the swap and backrun execute atomically in one on-chain transaction. nexroute does not dispatch the transaction in this mode; the partner (or the user’s wallet) submits it. Returns result: null when no profitable arbitrage is found, in which case the partner proceeds without a backrun.

Privacy is the dispatcher’s responsibility. If mempool exposure is a concern, the dispatching path must use a private relay.

Request

POST to your embedded endpoint with a JSON-RPC 2.0 envelope.

Params

params is a single-element array containing the user transaction description.

Field	Type	Required	Description
`to`	`string`	yes	Target contract the user transaction calls (e.g. the aggregator router).
`calldata`	`string`	yes	Hex-encoded calldata of the user transaction (the swap).
`value`	`string`	no	Native-token value attached to the user transaction, as a decimal string. Omit or set to `"0"` if none.
`tokenIn`	`string`	yes	Input token of the user swap.
`amountIn`	`string`	yes	Input amount as a decimal string in token base units.

Example

curl -X POST https://your-embedded-endpoint \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "eth_backrun",
    "params": [{
      "to": "0x1231deb6f5749ef6ce6943a275a1d3e7486f4eae",
      "calldata": "0x...",
      "value": "0",
      "tokenIn": "0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c",
      "amountIn": "1000000000000000000"
    }]
  }'

const response = await fetch('https://your-embedded-endpoint', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'eth_backrun',
    params: [{
      to: '0x1231deb6f5749ef6ce6943a275a1d3e7486f4eae',
      calldata: '0x...',
      value: '0',
      tokenIn: '0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c',
      amountIn: '1000000000000000000',
    }],
  }),
});

const data = await response.json();
console.log(data.result); // BackrunResult or null

Response

A JSON-RPC envelope echoing the request id. result is a BackrunResult object when a profitable backrun is found, or null when none.

BackrunResult

Field	Type	Description
`calldata`	`string`	Backrun calldata, pre-wrapped so the partner can plug it into the user transaction without further encoding.
`contract`	`string`	Address of the backrun contract the calldata targets.
`gas`	`integer`	Estimated gas for the backrun portion.
`profitToken`	`string`	Token in which the simulated gross profit is denominated.
`grossProfit`	`string`	Simulated gross profit in `profitToken` base units (decimal string).
`netProfitEth`	`string`	Simulated net profit after gas, denominated in the chain’s native token (decimal string). Use this to decide whether bundling is worth it on your side.
`netProfitUsd`	`string`	Simulated net profit in USD (decimal string, oracle-converted).

Examples

Backrun found

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "calldata": "0x...",
    "contract": "0x0000000000000000000000000000000000000000",
    "gas": 215000,
    "profitToken": "0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c",
    "grossProfit": "1234567890000000",
    "netProfitEth": "983456789000000",
    "netProfitUsd": "0.31"
  }
}

No profitable backrun

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": null
}

Errors

Code	Cause
`-32601`	Method not supported on this endpoint
`-32000`	Missing or malformed required field (`tokenIn`, `amountIn`, etc.)
`-32603`	Internal error during simulation (rare)

Getting started

RPC mode

Embedded mode

API reference

Request

Params

Example

Response

BackrunResult

Examples

Errors

​Request

​Params

​Example

​Response

​BackrunResult

​Examples

​Errors

Request

Params

Example

Response

BackrunResult

Examples

Errors