> For the complete documentation index, see [llms.txt](https://docs.ethgas.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ethgas.com/orderflow/api-reference.md). # API reference All public APIs available to originators and searchers are listed below. JSON-RPC calls use version `2.0`, a non-null string or integer `id`, and a one-element `params` array. JSON requests use `Content-Type: application/json`. ## Originator APIs ### Entry points | Transport | HTTP method | Endpoint | Authentication | Description | | --------- | ----------- | ------------------------------------------------------ | --------------- | ---------------------------------------------------------------- | | HTTPS | `POST` | `https://originator.orderflow.ethgas.com/v1` | None | Public endpoint for submitting originator JSON-RPC requests. | | HTTPS | `POST` | `https://originator.orderflow.ethgas.com/v1/{API_KEY}` | API key in path | Partner endpoint for authenticated originator JSON-RPC requests. | ### JSON-RPC methods | Method | Parameters | Description | Result | | ------------------------------- | ----------------------------------- | -------------------------------------------------------------------------------------- | ------------------------ | | `eth_sendRawTransaction` | `["0x"]` | Submit one signed transaction as private orderflow. | Transaction hash | | `eth_sendPrivateRawTransaction` | `["0x"]` | Alias of `eth_sendRawTransaction` for submitting one signed transaction. | Transaction hash | | `eth_sendPrivateTransaction` | `[{"tx":"0x"}]` | Submit one signed transaction using an object parameter. | Transaction hash | | `eth_sendBundle` | `[{"txs":[...], ...}]` | Submit an ordered bundle of signed transactions with optional block and refund fields. | `{"bundleHash":"0x..."}` | Every originator JSON-RPC method accepts the optional query `refund=
:`. The query override takes precedence over refund fields in an originator bundle body. ## Searcher APIs ### Entry points | Transport | HTTP method | Endpoint | Authentication | Description | | --------- | ------------- | ---------------------------------------------------- | --------------- | --------------------------------------------------------------------- | | HTTPS | `POST` | `https://searcher.orderflow.ethgas.com/v1/{API_KEY}` | API key in path | Submit authenticated searcher JSON-RPC requests over HTTP. | | WebSocket | `GET` upgrade | `wss://searcher.orderflow.ethgas.com/v1/{API_KEY}` | API key in path | Open a live orderflow stream and exchange searcher JSON-RPC messages. | ### JSON-RPC methods | Method | Transport | Parameters | Description | Result | | ------------------ | ------------------ | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | | `eth_subscribe` | WebSocket | `["ethgas_partialPendingBundles"]` | Return the ID of the automatic live orderflow subscription; calling it again is idempotent. | Subscription ID | | `eth_sendBundle` | HTTPS or WebSocket | `[{"txs":[...], ...}]` | Submit or replace a searcher bundle. An empty `txs` array with only `replacementUuid` cancels that replacement group. | `{"bundleHash":"0x..."}`; empty hash for cancellation | | `eth_cancelBundle` | HTTPS or WebSocket | `[{"replacementUuid":""}]` | Cancel the active bundles associated with a replacement UUID. | HTTP code `200` | ### WebSocket notification | Message | Direction | Description | Payload | | ------------------ | ------------------ | ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | | `eth_subscription` | Server to searcher | Deliver live decoded unsigned originator transactions for the automatic subscription. | `params.subscription` contains the subscription ID and `params.result` contains the ordered transaction array. | Opening the WebSocket creates the subscription automatically. Missed notifications are not replayed, and `eth_unsubscribe` is not supported. ## Account APIs These endpoints are available to provisioned originator and searcher accounts. To request an account or an originator refund-read-only subaccount, contact us at . | HTTP method | Endpoint | Authentication | Description | | ----------- | ------------------------------------------------------------------ | --------------------------------- | ---------------------------------------------------------------------- | | `GET` | `https://orderflow.ethgas.com/v1/auth/challenge?address={address}` | None | Issue an EIP-712 challenge for the account address. | | `POST` | `https://orderflow.ethgas.com/v1/auth/verify` | EIP-712 signature in request body | Verify the signed challenge and issue or rotate the account's API key. | | `GET` | `https://orderflow.ethgas.com/v1/auth/account` | Bearer API key | Return the identity and capabilities associated with the API key. | | `POST` | `https://orderflow.ethgas.com/v1/auth/api-keys/revoke` | Bearer API key | Revoke the current API key; the request body is an empty JSON object. | ## Tracking and refund APIs | Audience | HTTP method | Endpoint | Authentication | Description | | ----------------------------------------------- | ----------- | ---------------------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------ | | Originators | `GET` | `https://orderflow.ethgas.com/v1/tx/{txHash}` | None | Look up the public lifecycle status of an originator transaction by hash. | | Partner originators | `GET` | `https://orderflow.ethgas.com/v1/{API_KEY}/tx/{txHash}` | API key in path | Look up an owned transaction and include its private decoded body and refund policy. | | Originators and searchers | `GET` | `https://orderflow.ethgas.com/v1/bundle?hash={bundleHash}` | None | Look up an originator or searcher bundle's lifecycle and latest builder bundle hash. | | Partner originators and refund-read subaccounts | `GET` | `https://orderflow.ethgas.com/v1/{API_KEY}/refunds` | API key in path | List confirmed payouts and pending refund liabilities belonging to the partner originator. | --- # 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 If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.ethgas.com/orderflow/api-reference.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.