{"uid":"cap_n_z82vHNYGhlPmAmbhLEP","slug":"bullflow-peak-return-calculator-d2219cc4","name":"Bullflow Peak Return Calculator","description":"Bullflow.io is a real-time unusual options flow and dark pool tracker with advanced tools to view, filter, and analyze market activity as it happens.","url":"https://api.bullflow.io/v1/data/peakReturn?utm_source=zero.xyz","method":"GET","headers":{},"bodySchema":{"type":"object","$schema":"https://json-schema.org/draft/2020-12/schema","required":["input"],"properties":{"input":{"type":"object","required":["type","method"],"properties":{"type":{"type":"string","const":"http"},"method":{"enum":["GET"],"type":"string"},"queryParams":{"type":"object","required":["sym","old_price","trade_timestamp"],"properties":{"sym":{"type":"string","description":"Option contract symbol, for example O:SPY261016C00650000."},"old_price":{"type":"number","description":"Entry price in USD per share.","exclusiveMinimum":0},"trade_timestamp":{"type":"number","description":"Trade Unix timestamp in seconds.","exclusiveMinimum":0}}}},"additionalProperties":false},"output":{"type":"object","required":["type"],"properties":{"type":{"type":"string"},"example":{"type":"object","$schema":"https://json-schema.org/draft/2020-12/schema","required":["peakPriceSinceTimestamp","peakPercentReturnSinceTimestamp"],"properties":{"peakPriceSinceTimestamp":{"type":"string","description":"Highest option price in USD, formatted to two decimal places."},"peakPercentReturnSinceTimestamp":{"type":"number","description":"Peak return in percent relative to the supplied entry price."}}}}}}},"responseSchema":{"type":"json","example":{"peakPriceSinceTimestamp":"1.50","peakPercentReturnSinceTimestamp":11.11}},"example":null,"exampleRequest":null,"tags":["x402"],"displayCostAmount":"0.01","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"probe","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"static","summary":"$0.01/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.01","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.01","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_gL8K9kOSMcAFkHg7JVf7J","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.01","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Returns the peak (highest) price and maximum percent return achieved by an options contract since a specified entry trade timestamp and price.","exampleAgentPrompt":"Using Bullflow, what was the peak price and maximum percent return on the SPY options contract O:SPY261016C00650000 since it was entered at $0.50 per share at Unix timestamp 1712000000?","exampleUseCases":[{"title":"Validate unusual options flow trade performance","prompt":"I saw an unusual call sweep on SPY last week — the contract was O:SPY261016C00650000 and it was entered at $0.75 per share at timestamp 1711900000. What was the peak price and highest return on that contract since that trade?"},{"title":"Post-trade options performance review","prompt":"Can you check how well my SPY options trade did? I entered O:SPY261016C00650000 at $1.20 per share on Unix timestamp 1712500000 — I want to know the peak price and best percentage return it hit since then."},{"title":"Dark pool trade peak return analysis","prompt":"There was a dark pool options trade flagged on Bullflow for O:SPY261016C00650000 at an entry price of $0.30 per share and timestamp 1713000000. What's the peak return percentage since that trade was made?"}],"resultDescription":"Returns a JSON object with two fields: 'peakPriceSinceTimestamp' (the highest option price in USD formatted to two decimal places as a string) and 'peakPercentReturnSinceTimestamp' (the maximum percentage return relative to the provided entry price as a number). Example: {\"peakPriceSinceTimestamp\": \"1.50\", \"peakPercentReturnSinceTimestamp\": 11.11}.","failureModes":["Invalid or malformed option contract symbol returns an error","Entry price of zero or negative value rejected (exclusiveMinimum: 0)","Trade timestamp of zero or negative value rejected (exclusiveMinimum: 0)","Future timestamps or timestamps with no available data may return empty or null results","Contract symbol not found in Bullflow data may return a 404 or empty response","Network or API rate-limit errors may occur under high request volume"],"whenToPreferThis":"Use this endpoint when you need to retrospectively evaluate the best-case return on a specific options contract since a known entry point, especially for analyzing unusual options flow or dark pool trades tracked by Bullflow. It is ideal for performance attribution, trade journaling, or validating smart-money signals. Prefer this over general market data APIs when the context is unusual options activity and you have a precise entry price and timestamp to anchor the peak return calculation.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-10-29T07:07:04.670Z","isFirstParty":false,"canonicalSlug":"bullflow-peak-return-calculator-d2219cc4"}