Submit private bundles

Permissionless searcher intake#

External searchers can submit signed PulseChain transactions as a private bundle. No enrollment, account or API key is required. Your signing identity owns the bundle’s status, replacement and cancellation. It can be unfunded and can differ from the wallets signing the transactions.

You find, simulate and sign your own trades. BlockFerret assembles and independently verifies the final candidate, then may submit it through the Vouch relay.

POST https://rpc.blockferret.win/builders

Use this advanced endpoint for bundles. Ordinary wallets keep https://rpc.blockferret.win for eth_sendRawTransaction.

Start with fresh terms and context#

1. Call signed blockferret_getSearcherTerms with params: [{}]. Check liveSearcherBundles, permissionlessSearchers, liveBridgeReady and the deployed paymentRouter.
2. Fetch GET https://rpc.blockferret.win/v1/builder-context for the target block, parent hash, validator recipient and expiry. HTTP 503 means no active duty context; back off. Bundles do not require templateAvailable: true or access to a complete-block template.
3. Simulate your trade against the state where it will execute. Keep repayment, slippage and minimum-profit checks in your execution contract. Sign on chain ID 369.
4. Include the router payment, sign the exact JSON request body, and send eth_sendBundle.
5. Check owner-signed submission status, then successful canonical receipts for every transaction.

Choose your inclusion fee#

Pay a chosen amount of native PLS to the non-upgradeable SearcherPaymentRouter. The router pays 60% to the context’s validator recipient and 40% to BlockFerret, and emits verified payment evidence. The searcher keeps the remaining trade proceeds and covers transaction gas. This fee is not an automatic percentage of the searcher’s whole profit.

For an eligible Vouch fee-depositor proposer, half of BlockFerret’s router share is returned through the final validator payout in the same block, making the inclusion fee’s effective split 80/20. Ordinary priority tips go to the validator separately.

pay(bytes32 paymentId, uint256 targetBlock,
    bytes32 expectedParent, address payable proposerRecipient) payable

Read the router address from live terms. Use a nonzero payment ID, the exact target execution block, its parent hash and the context’s validator recipient. The payment ID is your application identifier, not the final bundle hash. Calling the router from your arb contract after profit checks settles trading and payment in one transaction. A separate final payment transaction inside the bundle is also supported.

The router rejects a wrong chain, block or parent and rolls back failed transfers. Any revert later in the same transaction rolls back its fee. Every transaction in a multi-transaction bundle must independently succeed; the builder rejects the entire candidate if one fails.

Final placement and verification#

The bridge retains the existing block’s execution prefix and appends your bundle contiguously immediately before the final validator payout. It does not provide a private orderflow feed or arbitrary insertion before an existing trade. A preceding-block quote alone cannot establish profitability at this final position.

Complete replay verifies gas, all receipts, unchanged retained transaction outcomes, validator payment and builder earnings. Independent state checks protect builder-owned funds, tokens, approvals and storage. Your fee must actually increase retained builder earnings and validator payment above the current candidate; self-funded transfers or drains of builder inventory cannot qualify.

Keep trades and loan repayment atomic. BlockFerret does not introduce delayed selling or assume that an unprofitable trade will recover later.

Capacity and scheduling#

Wallet intake has reserved capacity and is scheduled first. The builder forwards its own candidate before bounded external replay. Searcher work cannot extend the duty deadline. Back off on HTTP 429 or 503.

Track, replace and cancel#

A returned submission ID confirms queue acceptance. The bundle must still pass final verification, be selected, win an eligible relay duty and become canonical. Use the same signing identity for blockferret_getSubmissionStatus. Use a standard UUID in replacementUuid to replace or cancel a pending bundle.

Cancellation cannot recall a bid after commitment. Queues are held in memory; expiry or a restart can require resubmission. A transport timeout can follow acceptance, so check status and receipts before retrying. Signed bytes are never automatically sent to the public mempool.

Local client and API reference#

The downloadable Node.js client signs authentication locally. Read the API reference and downloadable guide. No private key belongs in the website.