{"openapi":"3.1.0","info":{"title":"Flea Liquidity API","version":"1.0.0","description":"One API for supported liquidity pools on Robinhood. Callers sign locally; private keys are never accepted. Both pool assets are required. No swaps or custody. Operations check two confirmations, not absolute chain finality."},"servers":[{"url":"https://flea.trade/api/v1"}],"paths":{"/capabilities":{"get":{"summary":"Supported network, actions, limits and boundaries","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["apiVersion","requestId","data"],"properties":{"apiVersion":{"const":"1"},"requestId":{"type":"string"},"data":{"type":"object"}}}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/pools":{"get":{"summary":"Find pools by token or pool ID, or page through ranked community pools","parameters":[{"name":"chainId","in":"query","required":false,"schema":{"type":"integer","enum":[4663],"default":4663}},{"name":"token","in":"query","required":false,"schema":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"}},{"name":"q","in":"query","required":false,"schema":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}([0-9a-fA-F]{24})?$"}},{"name":"protocol","in":"query","required":false,"schema":{"enum":["all","v2","v3","v4"]}},{"name":"available","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["apiVersion","requestId","data"],"properties":{"apiVersion":{"const":"1"},"requestId":{"type":"string"},"data":{"type":"object","properties":{"pools":{"type":"array","items":{"$ref":"#/components/schemas/Pool"}},"nextCursor":{"type":["string","null"]},"total":{"type":"integer"},"updatedAt":{"type":"string"}}}}}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/quote":{"post":{"summary":"Calculate paired amounts without requiring a funded wallet","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["poolId","token","amount"],"properties":{"chainId":{"type":"integer","enum":[4663],"default":4663},"poolId":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}([0-9a-fA-F]{24})?$"},"token":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"amount":{"type":"string","pattern":"^[0-9]+(\\.[0-9]+)?$","description":"Human-readable amount of token, never a floating-point JSON number."},"range":{"type":"string","enum":["full","wide"],"default":"full"},"slippageBps":{"type":"integer","minimum":1,"maximum":500,"default":50}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["apiVersion","requestId","data"],"properties":{"apiVersion":{"const":"1"},"requestId":{"type":"string"},"data":{"$ref":"#/components/schemas/Quote"}}}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/positions":{"get":{"summary":"Read a wallet’s positions; discovery is partial and externally created positions may need import","parameters":[{"name":"chainId","in":"query","required":false,"schema":{"type":"integer","enum":[4663],"default":4663}},{"name":"owner","in":"query","required":true,"schema":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"}},{"name":"refresh","in":"query","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["apiVersion","requestId","data"],"properties":{"apiVersion":{"const":"1"},"requestId":{"type":"string"},"data":{"type":"object","properties":{"positions":{"type":"array","items":{"$ref":"#/components/schemas/Position"}},"partial":{"type":"boolean"}}}}}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/positions/{positionId}":{"get":{"summary":"Read one owned position by its opaque Flea ID","parameters":[{"name":"positionId","in":"path","required":true,"schema":{"type":"string","description":"Opaque ID returned by Flea, e.g. v4:123 or v2:0x…"}},{"name":"owner","in":"query","required":true,"schema":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"}},{"name":"chainId","in":"query","required":false,"schema":{"type":"integer","enum":[4663],"default":4663}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["apiVersion","requestId","data"],"properties":{"apiVersion":{"const":"1"},"requestId":{"type":"string"},"data":{"$ref":"#/components/schemas/Position"}}}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/positions/import":{"post":{"summary":"Check ownership and remember an external position","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["owner","positionId"],"properties":{"chainId":{"type":"integer","enum":[4663],"default":4663},"owner":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"positionId":{"type":"string","description":"Opaque ID returned by Flea, e.g. v4:123 or v2:0x…"}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["apiVersion","requestId","data"],"properties":{"apiVersion":{"const":"1"},"requestId":{"type":"string"},"data":{"type":"object","properties":{"position":{"$ref":"#/components/schemas/Position"}}}}}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/operations":{"post":{"summary":"Create or resume an idempotent deposit, collect or withdrawal operation","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":16,"maxLength":128},"description":"Generate a random key per intended action. Reuse it when retrying; changed fields with the same key return 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OperationInput"}}}},"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["apiVersion","requestId","data"],"properties":{"apiVersion":{"const":"1"},"requestId":{"type":"string"},"data":{"$ref":"#/components/schemas/Operation"}}}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/operations/{id}":{"get":{"summary":"Read progress and check receipts on demand; no background polling","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["apiVersion","requestId","data"],"properties":{"apiVersion":{"const":"1"},"requestId":{"type":"string"},"data":{"$ref":"#/components/schemas/Operation"}}}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/operations/{id}/prepare":{"post":{"summary":"Refresh state and prepare exactly one unsigned transaction","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["apiVersion","requestId","data"],"properties":{"apiVersion":{"const":"1"},"requestId":{"type":"string"},"data":{"$ref":"#/components/schemas/Operation"}}}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/operations/{id}/submit":{"post":{"summary":"Verify and broadcast a locally signed prepared transaction","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["stepId","signedTransaction"],"properties":{"stepId":{"type":"string","format":"uuid"},"signedTransaction":{"type":"string","pattern":"^0x[0-9a-fA-F]+$","maxLength":14000}}}}}},"responses":{"202":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["apiVersion","requestId","data"],"properties":{"apiVersion":{"const":"1"},"requestId":{"type":"string"},"data":{"$ref":"#/components/schemas/Operation"}}}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/operations/{id}/reprice":{"post":{"summary":"Prepare replacement fees for the same pending nonce and action, within the accepted network budget","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["apiVersion","requestId","data"],"properties":{"apiVersion":{"const":"1"},"requestId":{"type":"string"},"data":{"$ref":"#/components/schemas/Operation"}}}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/operations/{id}/reconcile":{"post":{"summary":"Reconcile a successful owner-sent replacement or cancellation after two confirmations","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["hash"],"properties":{"hash":{"type":"string","pattern":"^0x[0-9a-fA-F]{64}$"}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["apiVersion","requestId","data"],"properties":{"apiVersion":{"const":"1"},"requestId":{"type":"string"},"data":{"$ref":"#/components/schemas/Operation"}}}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}}},"components":{"responses":{"Error":{"description":"Typed error. Rate limits return Retry-After. Provider details and credentials are never exposed.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"apiVersion":{"const":"1"},"requestId":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}},"schemas":{"OperationInput":{"oneOf":[{"type":"object","additionalProperties":false,"required":["action","owner","poolId","token","amount"],"properties":{"action":{"const":"deposit"},"chainId":{"type":"integer","enum":[4663],"default":4663},"owner":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"maxNetworkFeeWei":{"type":"string","pattern":"^[1-9][0-9]{0,77}$","default":"10000000000000000","description":"Maximum gas limit × max fee per gas for each transaction; does not include its ETH value."},"poolId":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}([0-9a-fA-F]{24})?$"},"token":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"amount":{"type":"string","pattern":"^[0-9]+(\\.[0-9]+)?$","description":"Human-readable amount of token, never a floating-point JSON number."},"range":{"type":"string","enum":["full","wide"],"default":"full"},"slippageBps":{"type":"integer","minimum":1,"maximum":500,"default":50}}},{"type":"object","additionalProperties":false,"required":["action","owner","positionId"],"properties":{"action":{"const":"collect"},"chainId":{"type":"integer","enum":[4663],"default":4663},"owner":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"maxNetworkFeeWei":{"type":"string","pattern":"^[1-9][0-9]{0,77}$","default":"10000000000000000","description":"Maximum gas limit × max fee per gas for each transaction; does not include its ETH value."},"positionId":{"type":"string","description":"Opaque ID returned by Flea, e.g. v4:123 or v2:0x…"}}},{"type":"object","additionalProperties":false,"required":["action","owner","positionId"],"properties":{"action":{"const":"withdraw"},"chainId":{"type":"integer","enum":[4663],"default":4663},"owner":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"maxNetworkFeeWei":{"type":"string","pattern":"^[1-9][0-9]{0,77}$","default":"10000000000000000","description":"Maximum gas limit × max fee per gas for each transaction; does not include its ETH value."},"positionId":{"type":"string","description":"Opaque ID returned by Flea, e.g. v4:123 or v2:0x…"},"percent":{"type":"integer","minimum":1,"maximum":100,"default":100}}}]},"Token":{"type":"object","required":["address","symbol","decimals"],"properties":{"address":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"symbol":{"type":"string"},"name":{"type":"string"},"decimals":{"type":"integer"},"logo":{"type":"string"}}},"Pool":{"type":"object","required":["id","protocol","token0","token1","eligible"],"properties":{"id":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}([0-9a-fA-F]{24})?$"},"protocol":{"enum":["v2","v3","v4"]},"origin":{"type":"string"},"token0":{"$ref":"#/components/schemas/Token"},"token1":{"$ref":"#/components/schemas/Token"},"fee":{"type":"integer","description":"Pool fee in millionths; 3000 means 0.3%."},"eligible":{"type":"boolean"},"earnsFees":{"type":"boolean"},"reason":{"type":"string"},"tvlUsd":{"type":"number"},"checkedAt":{"type":"string"},"manager":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"}}},"Quote":{"type":"object","properties":{"pool":{"$ref":"#/components/schemas/Pool"},"amount0":{"type":"string"},"amount1":{"type":"string"},"amount0Raw":{"type":"string"},"amount1Raw":{"type":"string"},"liquidity":{"type":"string"},"tickLower":{"type":"integer"},"tickUpper":{"type":"integer"},"slippageBps":{"type":"integer"},"expiresAt":{"type":"integer"},"warnings":{"type":"array","items":{"type":"string"}},"interfaceFeeBps":{"const":0}}},"Position":{"type":"object","properties":{"id":{"type":"string","description":"Opaque ID returned by Flea, e.g. v4:123 or v2:0x…"},"tokenId":{"type":"string"},"protocol":{"enum":["v2","v3","v4"]},"pool":{"$ref":"#/components/schemas/Pool"},"owner":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"liquidity":{"type":"string"},"amount0":{"type":"string"},"amount1":{"type":"string"},"inRange":{"type":"boolean"}}},"UnsignedTransaction":{"type":"object","required":["type","chainId","from","to","data","value","nonce","gas","maxFeePerGas","maxPriorityFeePerGas"],"properties":{"type":{"const":"eip1559"},"chainId":{"type":"integer","enum":[4663],"default":4663},"from":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"to":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"data":{"type":"string"},"value":{"type":"string","pattern":"^0x[0-9a-fA-F]+$","description":"Hexadecimal EVM quantity."},"nonce":{"type":"integer"},"gas":{"type":"string","pattern":"^0x[0-9a-fA-F]+$","description":"Hexadecimal EVM quantity."},"maxFeePerGas":{"type":"string","pattern":"^0x[0-9a-fA-F]+$","description":"Hexadecimal EVM quantity."},"maxPriorityFeePerGas":{"type":"string","pattern":"^0x[0-9a-fA-F]+$","description":"Hexadecimal EVM quantity."}}},"Step":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"kind":{"enum":["approval","wrap","deposit","collect","withdraw"]},"label":{"type":"string"},"expiresAt":{"type":"integer"},"transaction":{"$ref":"#/components/schemas/UnsignedTransaction"},"approval":{"type":"object","properties":{"token":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"spender":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"amountRaw":{"type":"string"},"unlimited":{"type":"boolean"},"expiresAt":{"type":"integer"}}},"hashes":{"type":"array","items":{"type":"string"}},"broadcastState":{"enum":["accepted","unknown"]}}},"Operation":{"type":"object","required":["id","input","status","createdAt","expiresAt","history"],"properties":{"id":{"type":"string","format":"uuid"},"input":{"$ref":"#/components/schemas/OperationInput"},"status":{"enum":["ready","awaiting-signature","pending","complete","failed","needs-review","expired","cancelled"]},"createdAt":{"type":"integer"},"expiresAt":{"type":"integer"},"revision":{"type":"integer"},"quote":{"$ref":"#/components/schemas/Quote","description":"Initial reviewed quote."},"currentQuote":{"$ref":"#/components/schemas/Quote","description":"Fresh quote used for the latest prepared step."},"position":{"$ref":"#/components/schemas/Position"},"step":{"$ref":"#/components/schemas/Step"},"history":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"hash":{"type":"string"},"hashes":{"type":"array","items":{"type":"string"}},"block":{"type":"string"},"status":{"enum":["confirmed","reverted"]}}}},"result":{"type":"object","properties":{"hash":{"type":"string"},"block":{"type":"string"},"positionIds":{"type":"array","items":{"type":"string","description":"Opaque ID returned by Flea, e.g. v4:123 or v2:0x…"}},"positionId":{"type":"string","description":"Opaque ID returned by Flea, e.g. v4:123 or v2:0x…"}}},"issue":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}