API reference
Requests, operation states, limits and recovery behavior for API v1.
Base URL and responses
Use https://flea.trade/api/v1 with JSON requests. Browser requests are supported through CORS. Successful responses contain apiVersion, requestId and data; errors contain error.code, error.message and optional field details. X-Request-Id is also returned as a header. Never put private keys or credentials in these requests.
{ "apiVersion": "1", "requestId": "...", "data": { ... } }
{ "apiVersion": "1", "requestId": "...",
"error": { "code": "REVIEW_REQUIRED", "message": "..." } }Discovery and positions
Address search accepts a token, V2/V3 pool address or full V4 pool ID. Pool eligibility is checked independently of ranking. Opaque position IDs should be passed back exactly as returned.
| Method | Path | Input |
|---|---|---|
| GET | /capabilities | Supported chain, actions, cache and limits |
| GET | /pools | token or q; protocol, available, cursor |
| POST | /quote | poolId, token, amount; range, slippageBps |
| GET | /positions | owner; refresh=true for a throttled refresh |
| GET | /positions/{positionId} | owner |
| POST | /positions/import | owner, positionId |
Operation endpoints
POST /operations requires an Idempotency-Key header of 16 to 128 letters, numbers, dots, underscores, colons or hyphens. Use a random UUID for each intended action. State is persisted so another process can resume using the operation ID. Treat that ID as an unlisted recovery reference; possession of it still cannot authorize a transfer without the wallet signature.
Operation creation and preparation need a funded wallet with the required assets. Use /quote for a preview without wallet balance checks. A create response includes the next prepared step when preparation succeeds. If preparation is temporarily unavailable, retry with the same key.
| Method | Path | Input |
|---|---|---|
| POST | /operations | action, owner and action fields |
| GET | /operations/{id} | Read state and check pending receipts |
| POST | /operations/{id}/prepare | {} |
| POST | /operations/{id}/submit | stepId, signedTransaction |
| POST | /operations/{id}/reprice | {} |
| POST | /operations/{id}/reconcile | hash of confirmed owner replacement |
Amounts and limits
Amounts are decimal strings in human token units, such as "100.5". Raw amounts and liquidity are integer strings. Transaction quantities are hexadecimal strings; the JavaScript client converts them to BigInt for a local EVM signer. chainId is 4663 and omitted values default to it. Other networks are rejected.
Deposits accept full or wide range, with full as the default. slippageBps is an integer from 1 to 500, default 50. The initial quote is preserved in quote, while currentQuote records the latest prepared amounts. Later preparations must stay inside the reviewed amount, liquidity and tick bounds; on-chain minimums follow the selected pool adapter. A quote is an estimate, not a guaranteed LP return.
A prepared step expires after two minutes and an operation accepts new steps for one hour. Pending receipts remain readable after expiry. Already submitted bytes can still be retried. EIP-1559 EOA transactions are supported; smart-account user operations and private-key custody are not. Up to twelve preparation steps and five submitted replacement hashes per step are allowed.
Operation states
| State | Meaning | Next action |
|---|---|---|
| ready | Previous preparation step confirmed | POST prepare |
| awaiting-signature | Fresh unsigned transaction available | Review, sign locally, POST submit |
| pending | Hash recorded, receipt not yet confirmed | Poll GET; retry identical bytes if broadcast is unknown |
| complete | Final action confirmed; deposit ownership verified | Save result and position IDs |
| needs-review | Market changed or receipt needs inspection | Review issue and existing hashes before a new operation |
| failed | Transaction reverted | Inspect issue; earlier steps remain on-chain |
| expired | No new signatures accepted | Check history before a new intended action |
| cancelled | Owner replaced the pending nonce with another action | Inspect replacement |
Errors and safe retries
429 responses include Retry-After. Retry a network timeout, OPERATION_BUSY or 503 with backoff and the same idempotency key or signed bytes. Never generate a new key just because a response was lost. The bundled client retries transient requests up to five times and includes recovery identifiers when it stops.
STEP_EXPIRED and STALE_STEP require preparing the current step. REVIEW_REQUIRED asks for a fresh reviewed operation. FEE_LIMIT_EXCEEDED requires reviewing the accepted network budget, not silently increasing it. NONCE_CONFLICT means another submitted Flea operation owns that nonce.
A signed hash is saved before broadcast, including when the RPC response times out. Successful repeated submission of the same step returns its current state. Reprice changes only fees for the same pending action and nonce within the original budget; it cannot extend a contract deadline. Reconcile accepts a successful replacement from the same wallet and nonce after two confirmations.
Caching and request budgets
Pool discovery and wallet positions are cached for five minutes. Ranked market refresh is demand-driven, at most once every ten minutes. Quote previews share short pool reads; execution preparation refreshes balances, allowances and pool state. Pending receipt reads share a two-second cache. No operation worker polls while nobody requests it.
The public service allows 60 reads and 30 writes per IP per minute, including at most 10 operation creations and two explicit wallet refreshes. Creation is also limited to 60 requests per process per minute, with three concurrent operation updates. The global RPC budget and bounded request queue protect the site under load; callers must handle backoff.
JSON request bodies are limited to 16 KiB. Terminal operation records are kept for at least 30 days; abandoned unsigned records can be removed after one day. Pending records are retained for recovery. Save final receipts in your own application.