Submission Methods

Types of Submissions

Bundles and Kairos (Top of Block) Fastbids can be submitted to the FastLane Relay RPC endpoint using JSON-RPC 2.0 over HTTPS and Websocket.

Searchers can send their submissions to the FastLane Relay API by calling the methods pfl_addSearcherBundle for Bundles or pfl_addSearcherFastBid for Kairos (Top of Block) Fastbids.

More information on the FastLane Relay API and API calls can be found here:

pageRelay JSON-RPC API

Rate limits (for both HTTP and websocket):

Request/message limit per second: 2

Burst limit: 32

Repeatedly going over the rate limit will result in temporary IP ban, ranging from 3 minutes to 24 hours.

HTTPS

It's recommended that you use HTTP Keep-Alive connections to connect to the RPC endpoint to minimize TLS connection establishment times as it significantly reduces request latency when sending a bundle if the TLS handshake is already complete.

The /ping endpoint is available for establishing a session, you can have a maximum of 2 sessions per IP address, and sessions will persist for a maximum of 15 minutes.

Example:

Javascript

// node LTS (v18.12.1)
// consider node-fetch to replace native fetch for lower

const https = require("https");

const RELAY = "https://beta-rpc.fastlane-labs.xyz";

const pfl_bundle =  createBundle(); // See submitFlashBid js doc

const postData = {
  jsonrpc: "2.0",
  method: "pfl_addSearcherBundle",
  params: [pfl_bundle],
  id: 1,
};

const agent = new https.Agent({
  keepAlive: true,
});

const ping = () => fetch(`${RELAY}/ping`, { agent }).then(r => console.log(`PONG : ${r.statusText}`));

const sendBundle = postData => fetch(RELAY, {
    method: "POST", // or 'PUT',
    agent,
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify(postData),
});

const keepWarm = async() => {
    setInterval(ping, 1000*60*10);
    return ping();
}

async function main() {
  // Warm it up.
  await keepWarm();

  // Whenever needed. Fire a bundle.
  await sendBundle(postData)
    // See https://fastlane-labs.gitbook.io/polygon-fastlane/reference/relay-json-rpc-api 
    // as response can still have a .error field
    .then(async(response) => {
      console.log("Success:", response.statusText);

      const json = await response.json();
      console.log(json);

      if (json.error) throw json.error.message;
    })
    .catch((error) => {
      console.error("Error:", error);
    });
};

main().catch(err => console.error(err));


// Additional ressources:
// - https://github.com/node-fetch/node-fetch#custom-agent
// - https://www.npmjs.com/package/agentkeepalive

Python

import requests

pfl_bundle = [ ]  # array of Searcher Transactions, from above

s = requests.Session() # start a session for Keep-Alives

s.get('https://beta-rpc.fastlane-labs.xyz/ping') # open tls connection

# wait until you're ready to send a bundle, refreshing session as necessary

# submit the bundle!
rsp = s.post('https://beta-rpc.fastlane-labs.xyz', json={
  "jsonrpc": "2.0",
  "method": "pfl_addSearcherBundle",
  "params": [pfl_bundle],
  "id": 1,
})

Websocket

Ping messages will be sent to your connection every 60 seconds. A pong response must be sent to avoid disconnection. Alternatively, you can send ping messages yourself to the server every minutes and get pong responses.

To keep a websocket connection open and stable on a long term, we highly recommend to send ping messages to the server every minutes, and to answer pong every time the server sends a ping message.

To better track responses (e.g. when sending multiple concurrent requests), it is highly advised to specify a unique id for each new requests, see example below.

Example:

Javascript

import WebSocket from 'ws';

const pflBundle = createBundle(); // See submitFlashBid js doc
const rpcData = {
    id: 25,
    jsonrpc: "2.0",
    method: "pfl_addSearcherBundle",
    params: [pflBundle],
};

let ws = new WebSocket("wss://beta-rpc.fastlane-labs.xyz/ws");
ws.on('open', function open() {
    console.log('websocket connected');
});
ws.on('message', function message(data) {
    console.log('Received:', data.toString());
    // output:
    // Received: {"id": 25, "jsonrpc": "2.0", "result": "..."}
    //                  ^ "id" matches the one we specified in the request
});

conn.send(JSON.stringify(rpcDataData));

Python

import json
import asyncio
from websockets.sync.client import connect

def send_bundle():
    pfl_bundle = []  # array of Searcher Transactions, from above
    with connect("wss://beta-rpc.fastlane-labs.xyz/ws") as websocket:
        websocket.send(json={
            "id": 25,
            "jsonrpc": "2.0",
            "method": "pfl_addSearcherBundle",
            "params": [pfl_bundle],
        })
        
        response = websocket.recv()
        print(f"Received: {response}")
        # output:
        # Received: {"id": 25, "jsonrpc": "2.0", "result": "..."}
        #                  ^ "id" matches the one we specified in the request

send_bundle()