Polygon Private Transaction APIs for Developers - Hyperstrate – Private Transaction Infrastructure for Polygon

A private transaction API looks simple from the outside: you POST a signed transaction and get a hash back. Building a reliable integration around it takes more thought. You need to handle authentication, signing, nonces, fees, status tracking, retries and errors in a way that never leaks the transaction to the public mempool by accident. This guide covers the concepts and decisions involved in integrating a Polygon private transaction API, whichever provider you use.

In short: a Polygon private transaction API is an authenticated JSON-RPC endpoint that accepts signed transactions and routes them privately toward block production. Sign locally, authenticate every request, manage nonces and fees yourself, track status until the transaction is final, and make retries idempotent.

What a private transaction API is

At its core, a private transaction API is a JSON-RPC endpoint that implements the write side of the Ethereum JSON-RPC interface used by Polygon PoS. You send a signed transaction; the provider validates it and forwards it through private infrastructure toward block production, rather than gossiping it to the public mempool.

Providers differ in a few details:

Method name. Some accept the standard eth_sendRawTransaction. Others expose a dedicated method such as eth_sendPrivateTransaction, a name first popularized on Ethereum, sometimes with extra options. Check your provider’s API reference.
Read support. Some endpoints serve reads as well; others handle submission only.
Status reporting. Providers report progress in their own way. Hyperstrate reports each transaction as received, private route established, propagated, included and settled.

A typical request looks like this:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_sendRawTransaction",
  "params": ["0x02f8b1818982...signed transaction bytes..."]
}

and a successful response returns the transaction hash:

{ "jsonrpc": "2.0", "id": 1, "result": "0x8f3c...a91e" }

Authentication

Private transaction APIs are authenticated so the provider can attribute usage, apply limits and bill correctly. Usually that means an API key sent in a header or embedded in the endpoint URL.

Keep keys server-side. Never ship an API key in front-end code or a mobile app bundle. If a browser wallet needs private submission, proxy requests through your backend or use a provider feature designed for client use.
Use separate keys for environments and services, so you can rotate one without touching the others.
Store keys in a secret manager, not in source control or plain configuration files.
Rotate on suspicion. If a key may have leaked, revoke it and issue a new one.

Signed transactions

The API never needs your private key. You sign locally and send the signed bytes.

Transaction type. Modern Polygon transactions use the EIP-1559 type (type 2), with maxFeePerGas and maxPriorityFeePerGas. Libraries such as ethers.js and viem build these by default.
Chain ID. Polygon PoS mainnet uses chain ID 137. The chain ID is part of the signature, which prevents a transaction from being replayed on another network.
The hash is deterministic. The transaction hash is the Keccak-256 hash of the signed bytes, so you know it before you submit. Use it as your idempotency key.

Nonces

Each transaction from an address carries a nonce, and they must be used in order. For a low-volume integration, asking the network for eth_getTransactionCount(address, "pending") before each send is fine. For bots and high-throughput backends:

Track the next nonce locally per sending address, and serialize sends from each address.
Resynchronize from the network after errors such as nonce too low.
Remember that a missing nonce blocks every later transaction from that address until it is filled or replaced.
Use several sending addresses if you need parallelism.

Fees

Polygon PoS uses an EIP-1559 fee market: a base fee set by the protocol plus a priority fee you choose. Polygon nodes also enforce a minimum priority fee, so transactions priced below it are rejected or never picked up.

Use eth_feeHistory or eth_maxPriorityFeePerGas from your read RPC to choose fees.
Set maxFeePerGas with headroom above the current base fee so a small base fee increase does not strand the transaction.
To replace a pending transaction, resend with the same nonce and higher fees. Nodes typically require a meaningful increase, often at least 10% on both fee fields.

Status tracking

The hash you get back means the transaction was accepted, not that it was included. Track it through three layers:

Provider status. What the private route did with it. Use your provider’s status reporting.
Inclusion. eth_getTransactionReceipt returns a receipt once the transaction is in a block. status is 0x1 for success and 0x0 for a revert.
Finality. Polygon PoS supports the finalized block tag. Once the latest finalized block number is at or above your transaction’s block, the Polygon documentation describes it as irreversible.

Decide in advance how long you will wait for inclusion before you treat a transaction as stuck.

Retries and idempotency

Retries are where integrations most often go wrong.

Resending the same signed transaction is safe. It has the same hash, so it can be included at most once. An already known response means the provider or node already has it.
Replacing is a new transaction. Same nonce, higher fees, new hash. Track both hashes until one is included.
Never fall back to public broadcast. Sending the transaction to a public RPC because the private one seems slow puts it in the public mempool and defeats the purpose.
Use timeouts and backoff on HTTP calls, and treat network errors as “unknown” rather than “failed”: the transaction may have been accepted.

Common errors

Error	Meaning	Typical fix
`nonce too low`	That nonce was already used	Resync the nonce and rebuild
`replacement transaction underpriced`	A pending transaction uses this nonce with similar fees	Raise both fee fields or wait
`insufficient funds for gas * price + value`	Balance too low for the worst-case cost	Top up POL or reduce value or gas limit
`already known`	The same signed transaction was already submitted	Track the existing hash
`transaction underpriced`	Fee below the node’s minimum	Raise the priority fee
HTTP 401 or 403	Missing or invalid API key	Check the key and header
HTTP 429	Rate limit reached	Back off and retry later

Exact messages vary between providers and node versions, so match on error codes and patterns rather than full strings where you can.

Testing

Polygon’s public testnet is Amoy (chain ID 80002). If your provider supports a test environment, run your integration against it first. Either way, start on mainnet with small, low-risk transactions, and test failure paths deliberately: a used nonce, an underpriced fee and a reverting call.

Integration checklist

API key stored server-side and rotated on schedule.
Transactions signed locally with chain ID 137.
Nonce tracking per address, with resync on errors.
Fee selection from recent fee history, with headroom.
Status tracked from acceptance through inclusion to finality.
Retries that resend or replace, never broadcast publicly.
Logging of hash, nonce, fees, timings and final status for every transaction.

Frequently asked questions

Do private transaction APIs on Polygon need my private key?

No. You sign locally and send only the signed transaction. Any service that asks for your private key is not following normal practice.

Can I use ethers.js or viem with a private transaction API?

Yes. Both can sign a transaction and send the raw bytes to any JSON-RPC endpoint, including one that requires an API key header. See how to send private transactions on Polygon for code.

How do I know whether a private transaction failed?

If it is not included, there is no receipt; your provider’s status and your timeout tell you it is stuck or dropped. If it is included but reverts, the receipt has status 0x0.

Conclusion

A Polygon private transaction API is a small surface with real responsibilities around it: authentication, signing, nonces, fees, status and retries. Get those right and private submission becomes a dependable part of your stack rather than a source of stuck transactions.

Hyperstrate provides one authenticated JSON-RPC endpoint for private transaction submission on Polygon, with status reporting from acceptance to settlement and pricing based on what happens to each transaction. See the developer examples and pricing, or talk to our team.