Operations-Relay API

This API provides HTTP and websocket endpoints, respectively for Atlas auctioneers and solvers.

Auctioneers access the HTTP endpoint to submit user operations for propagation to the solver network, and to collect solver operations.

Solvers access the websocket endpoint to stream new user operations and submit their solutions.

Solver JSON RPC Methods

solver_subscribe

This method subscribes to a particular topic. Notification messages are sent following a successful subscription.

info

Currently, only the userOperations topic is available.

Parameters

Type	Description
string	The subscription topic.

Returns

Type	Description
string	A unique subscription ID that will be referenced in every notification messages.

Notification

note

Notification data is located at params.result, see an example notification in the below section.

Type	Description
AuctionData	The new auction data map (see below).

AuctionData

Name	Type	Description
auction_id	string	The unique ID for this auction.
partial_user_operation	PartialUserOperation	The partial user operation map (see below).

PartialUserOperation

Name	Type	Description
chainId	string	The chain ID, hex encoded.
userOpHash	string	The user operation hash.
to	string	The user operation to field.
gas	string	The user operation gas field, hex encoded.
maxFeePerGas	string	The user operation maxFeePerGas field, hex encoded.
deadline	string	The user operation deadline field, hex encoded.
dapp	string	The user operation dapp field.
control	string	The user operation control field.
hints	[]string	An array of hint addresses (optional).
from	string	The user oepration from field (optional).
value	string	The user operation value field, hex encoded (optional).
data	string	The user operation data field (optional).

warning

The fields hints and (from, value, data) are mutually exclusive. Only one or the other can be present.

Example Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "solver_subscribe",
  "params": ["userOperations"]
}

Example Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "5ed17bf8-ed27-4625-97ef-447554594a3c"
}

Example Notification

{
  "jsonrpc": "2.0",
  "method": "solver_subscription",
  "params": {
    "subscription": "5ed17bf8-ed27-4625-97ef-447554594a3c",
    "result" : {
      "auction_id": "1bc9a4ce-4fcf-4eb1-8632-959e2273953e",
      "partial_user_operation": {...}
    }
  }
}

solver_submitSolverOperation

Submits a solution to the operations-relay.

Parameters

Type	Description
SolutionData	The solution data map (see below).

SolutionData

Name	Type	Description
auction_id	string	The unique auction ID, received with the user operation notification.
auction_solution	SolverOperation	The SolverOperation data map (see below).

SolverOperation

Name	Type	Description
from	string	Solver from field.
to	string	Solver to field.
value	string	Solver value field, hex encoded.
gas	string	Solver gas field, hex encoded.
maxFeePerGas	string	Solver maxFeePerGas field, hex encoded.
deadline	string	Solver deadline field, hex encoded.
solver	string	Solver solver field.
control	string	Solver control field.
userOpHash	string	Solver userOpHash field.
bidToken	string	Solver bidToken field.
bidAmount	string	Solver bidAmount field, hex encoded.
data	string	Solver data field.
signature	string	Solver signature field.

Returns

An empty result on success.

Example Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "solver_submitSolverOperation",
  "params": [{
    "auction_id": "1bc9a4ce-4fcf-4eb1-8632-959e2273953e",
    "auction_solution": {...}
  }]
}

Example Response

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

info

Empty result is expected on successful submission.

solver_identify

Authenticates to the operations-relay. Authenticated solvers will receive notifications (user operations) they are whitelisted for. It is typically not necessary for a solver to authenticate themselves, unless they've been explicitly told to do so and included in a dApp allowlist.

Parameters

Type	Description
AuthData	The authentication data map (see below).

AuthData

Name	Type	Description
address	string	The Ethereum address of the solver (the one signing the payload).
timestamp	uint	The timestamp in seconds when the payload was generated.
signature	string	The hex encoded signature of the Ethereum message (EIP 191) of the keccak256 of address and timestamp, concatenated without separator.

Returns

Type	Description
boolean	Returns true in case of success.

Example Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "solver_identify",
  "params": [{
    "address": "0x1234567890123456789012345678901234567890",
    "timestamp": 1759297991,
    "signature": "0x123456..."
  }]
}

Example Response

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

Auctioneer JSON RPC Methods

relay_userOperation

Submit a UserOperation to the relay for propagation to the solver network.

Parameters

Name	Type	Description
userOperation	UserOperationPartial	The UserOperation to submit.

Returns

Type	Description
auctionId	The auction ID of the resultant auction.
auctionSecret	An auth secret for retrieving solver operations submitted for this auction.

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "relay_userOperation",
  "params": [
    {
      "chainId": "0x2105",
      "userOpHash": "0x21d03d618fa4fb9166ae91f199b774b64390b8bf6ecdd2ae4637096e7b60e5e3",
      "to": "0xb25BdDC2180cF83B3ECb1eDE074a177c9C7Acc5f",
      "gas": "0x4e20",
      "maxFeePerGas": "0x4c4b40",
      "deadline": "0x19d8c75",
      "dapp": "0x43b4aae0f98fc9ebd86a1e9496cdb9d7208ee55b",
      "control": "0x43b4aae0f98fc9ebd86a1e9496cdb9d7208ee55b",
      "value": "0x0",
      "data": "0x1ad6fbc3",
      "from": "0xfc8b8974fc3adb8281a6c4c38d7cc895769a8568",
    }
  ]
}

Example Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "auctionId": "abcd12-345678-901234",
    "auctionSecret": "12042c-123456-789012"
  }
}

relay_solverOperations

Retrieve SolverOperations for a given auction.

Parameters

Name	Type	Description
auctionId	string	The auction ID of the auction to retrieve solver operations for.
auctionSecret	string	The auth secret for the auction.

Returns

Type	Description
solverOperations	SolverOperation[]

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "relay_solverOperations",
  "params": ["abcd12-345678-901234", "12042c-123456-789012"]
}

Example Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    [
      {
        "from": "0xfc8b8974fc3adb8281a6c4c38d7cc895769a8568",
        "to": "0xb25BdDC2180cF83B3ECb1eDE074a177c9C7Acc5f",
        "value": "0x0",
        "gas": "0x4e20",
        "maxFeePerGas": "0x4c4b40",
        "deadline": "0x19d8c75",
        "solver": "0x1234567890123456789012345678901234567890",
        "control": "0x43b4aae0f98fc9ebd86a1e9496cdb9d7208ee55b",
        "userOpHash": "0x21d03d618fa4fb9166ae91f199b774b64390b8bf6ecdd2ae4637096e7b60e5e3",
        "bidToken": "0x43b4aae0f98fc9ebd86a1e9496cdb9d7208ee55b",
        "bidAmount": "0x10",
        "data": "0x1ad6fbc311223344",
        "signature": "0x1234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890"
      }
    ]
  }
}