> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nexroute.io/llms.txt
> Use this file to discover all available pages before exploring further.

# eth_backrun

> Get ready-to-use backrun calldata for a user transaction over JSON-RPC

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.

<Note>
  Privacy is the dispatcher's responsibility. If mempool exposure is a concern, the dispatching path must use a private relay.
</Note>

## 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

<CodeGroup>
  ```bash cURL theme={null}
  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"
      }]
    }'
  ```

  ```javascript Node.js theme={null}
  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
  ```
</CodeGroup>

## 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

```json Backrun found theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "calldata": "0x...",
    "contract": "0x0000000000000000000000000000000000000000",
    "gas": 215000,
    "profitToken": "0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c",
    "grossProfit": "1234567890000000",
    "netProfitEth": "983456789000000",
    "netProfitUsd": "0.31"
  }
}
```

```json No profitable backrun theme={null}
{
  "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)                           |