API Reference

The searcher surface is gRPC, defined in Flowra's mev-protos Public repo TBD . The layout is compatible with the proto conventions most Solana MEV tooling already speaks, so existing client code ports with minimal changes.

AuthService (auth.proto)

Method	Type	Description
GenerateAuthChallenge	unary	Returns a challenge string for a (role, pubkey) pair. Searchers use role SEARCHER.
GenerateAuthTokens	unary	Exchanges the signed challenge (sign the exact string "{pubkey}-{challenge}", Ed25519, 64-byte signature) for tokens.
RefreshAccessToken	unary	Renews an access token using the refresh token.

Tokens are JWTs with explicit expiry timestamps. Attach the access token as gRPC bearer metadata on all other calls; refresh with the longer-lived refresh token rather than re-signing.

SearcherService (searcher.proto)

Method	Type	Description
SubscribePendingTransactions	server-streaming	The open orderflow stream: pending transaction packet batches from participating validators. See Orderflow Stream.
SendBundle	unary	Submits a signed bundle (up to 5 transactions) into the auction. Returns the server-assigned bundle uuid.
SubscribeBundleResults	server-streaming	Pushes BundleResult state transitions for your submitted bundles as they occur.
GetTipAccounts	unary	Returns the tip accounts to transfer lamports to; the transfer sum is your auction bid.
GetNextScheduledLeader	unary	Current slot plus the next connected leader's slot, identity, and region.
GetConnectedLeaders	unary	Leader slots for connected validators in the current epoch (this region).
GetConnectedLeadersRegioned	unary	Same, across the requested regions.
GetRegions	unary	The region you are connected to and all available regions.

Bundle results (bundle.proto)

A submitted bundle moves through a explicit state machine, streamed via SubscribeBundleResults:

State	Meaning
Accepted	Won its auction and was forwarded to a validator (includes slot and validator identity). Emitted once per forwarded validator.
Rejected / StateAuctionBidRejected	Outbid within its state auction (the contest among bundles touching the same accounts). Includes the auction id and your simulated bid in lamports.
Rejected / WinningBatchBidRejected	Won its state auction but did not make the tick's final winning set. Includes auction id and simulated bid.
Rejected / SimulationFailure	A transaction in the bundle failed simulation; includes the offending signature.
Rejected / DroppedBundle	Dropped before auction, for example when no connected leader is upcoming.
Rejected / InternalError	Engine-side error; safe to retry.
Processed	Landed on-chain (validator identity, slot, and index within the block).
Finalized	Reached finalized commitment.
Dropped	Forwarded but never landed: BlockhashExpired, PartiallyProcessed (another copy of a transaction landed first, invalidating atomicity), or NotFinalized (fork).

The two rejection types with bid values are your primary market-feedback signal; see Bundles.

Error semantics

Transport-level errors follow standard gRPC status codes:

Code	Meaning	Typical causes
UNAUTHENTICATED	Token missing or expired	Refresh your access token
INVALID_ARGUMENT	Request rejected at validation	Unsigned packet, more than 5 transactions, malformed bundle
UNAVAILABLE	Transient transport failure	Reconnect with exponential backoff

INVALID_ARGUMENT responses carry a human-readable reason; log them verbatim.

Limits

Limit	Value
Transactions per bundle	5
Concurrent result subscriptions	One per authenticated identity is sufficient; results are keyed by bundle uuid
Per-identity rate limits	Planned; sized so honest strategies are unaffected

Retry policy

On UNAVAILABLE: exponential backoff starting at 100 ms, doubling to a 5 s cap, with jitter. Do not tight-loop resubmit a rejected bundle; losing bundles already re-enter subsequent ticks automatically for a few seconds.

SDKs

Language SDKs (Rust, TypeScript, Python) wrapping auth, streaming, and submission are planned for GA TBD . Until then, the protos compile cleanly with standard tonic, grpc-js, and grpcio toolchains.