{"openapi":"3.0.3","info":{"title":"Lotus Network API","description":"Seven pay-per-call services on Base, settled in USDC over x402: video generation, image generation, audio and video transcription, PDF-to-Markdown conversion, and an auditable gas forecasting loop that journals a prediction and later verifies it against the chain. No API key, account, or subscription.","version":"1.4.0","contact":{"email":"blacklotusfinance.pls@gmail.com"}},"servers":[{"url":"https://lotusnetworkapi.com"}],"paths":{"/api/v1/generate-image":{"get":{"operationId":"generateImage","summary":"Generate an image from a text prompt","tags":["Media"],"description":"Text-to-image generation powered by FLUX.2 [pro]. Send a prompt, get back a 1024x1024 image as base64 JSON or raw bytes, plus a durable direct URL. No API key or account needed.","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.080000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"prompt":{"type":"string"},"model":{"type":"string"},"mimeType":{"type":"string"},"image":{"type":"string","description":"Base64-encoded image"},"absoluteUrl":{"type":"string"},"downloadUrl":{"type":"string"},"retentionDays":{"type":"number"}}},"example":{"success":true,"prompt":"a cyberpunk city skyline at dusk, neon reflections","model":"black-forest-labs/flux-2-pro","mimeType":"image/webp","image":"<base64-encoded image bytes>","absoluteUrl":"https://lotusnetworkapi.com/api/v1/image/9f2c4a1e7b3d5f8091a2b3c4d5e6f708"}}}},"402":{"description":"Payment required. Terms are in the PAYMENT-REQUIRED response header."}},"parameters":[{"name":"prompt","in":"query","required":true,"description":"Text description of the image to generate","schema":{"type":"string"},"example":"a cyberpunk city skyline at dusk, neon reflections"},{"name":"format","in":"query","required":false,"description":"json returns base64 plus a durable URL; binary returns raw image bytes","schema":{"type":"string","enum":["json","binary"],"default":"json"}}]}},"/api/v1/pdf-to-markdown":{"post":{"operationId":"pdfToMarkdown","summary":"Convert a PDF into clean Markdown text","tags":["Data"],"description":"Extracts text from a PDF and returns clean Markdown: unwrapped paragraphs, detected headings and bullet lists, no page furniture. Accepts a public PDF URL or base64 bytes. Built for agents that need to read documents they cannot parse natively.","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.005000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"pages":{"type":"number"},"characters":{"type":"number"},"title":{"type":"string"},"markdown":{"type":"string"}}},"example":{"success":true,"pages":12,"characters":18432,"title":"Quarterly Report","markdown":"# Quarterly Report\n\nRevenue grew 14% year over year..."}}}},"402":{"description":"Payment required. Terms are in the PAYMENT-REQUIRED response header."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"Public URL of a PDF to fetch and convert"},"pdf":{"type":"string","description":"Base64-encoded PDF bytes (alternative to url)"},"pageMarkers":{"type":"boolean","default":false}}},"example":{"url":"https://example.com/whitepaper.pdf"}}}}}},"/api/v1/video":{"post":{"operationId":"generateVideo","summary":"Generate a short video from a prompt or a starting image","tags":["Media"],"description":"Text-to-video and image-to-video generation at 1080p, up to five seconds. Returns a job id immediately; poll the free status endpoint until it completes, then collect an MP4 stored on a durable URL. Generation typically takes one to three minutes. No API key or account needed.","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"1.500000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status":{"type":"string","enum":["processing"]},"jobId":{"type":"string"},"statusUrl":{"type":"string","description":"Free endpoint; poll until status is completed"},"pollAfterSeconds":{"type":"number"}}},"example":{"success":true,"status":"processing","jobId":"3f9a2c1b4d6e8f0a1b2c3d4e5f607182","statusUrl":"https://lotusnetworkapi.com/api/v1/jobs/3f9a2c1b4d6e8f0a1b2c3d4e5f607182","pollAfterSeconds":20}}}},"402":{"description":"Payment required. Terms are in the PAYMENT-REQUIRED response header."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"string","description":"What the video should show"},"imageUrl":{"type":"string","description":"Optional starting frame for image-to-video"},"durationSeconds":{"type":"integer","minimum":3,"maximum":5,"default":5}},"required":["prompt"]},"example":{"prompt":"a paper boat drifting down a rain-filled gutter","durationSeconds":5}}}}}},"/api/v1/transcribe":{"post":{"operationId":"transcribeAudio","summary":"Transcribe audio or video into timestamped text","tags":["Data"],"description":"Speech-to-text with timestamped segments, for recordings an agent cannot listen to directly: podcasts, meetings, earnings calls, lecture audio. Give a public URL to an audio or video file. Returns a job id immediately; poll the free status endpoint for the transcript. Handles files up to several hours. No API key or account needed.","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.500000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status":{"type":"string","enum":["processing"]},"jobId":{"type":"string"},"statusUrl":{"type":"string"},"pollAfterSeconds":{"type":"number"}}},"example":{"success":true,"status":"processing","jobId":"8c2d1e4f6a9b0c3d5e7f8091a2b3c4d5","statusUrl":"https://lotusnetworkapi.com/api/v1/jobs/8c2d1e4f6a9b0c3d5e7f8091a2b3c4d5","pollAfterSeconds":15}}}},"402":{"description":"Payment required. Terms are in the PAYMENT-REQUIRED response header."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"audioUrl":{"type":"string","description":"Public URL of an audio or video file"},"language":{"type":"string","description":"ISO code such as en; omit to auto-detect"},"translate":{"type":"boolean","description":"Translate the transcript into English"}},"required":["audioUrl"]},"example":{"audioUrl":"https://example.com/earnings-call.mp3"}}}}}},"/api/v1/gas/preflight":{"get":{"operationId":"gasPreflight","summary":"Current Base gas conditions with a calibrated forecast range","tags":["Data"],"description":"Read-only Base L2 gas conditions computed directly from chain data: current base fee, recent percentiles, realised volatility, congestion state, and an 80% forecast range for a chosen horizon. This is supporting context for timing a transaction, not a trade instruction. Every figure is reproducible from public Base RPC data.","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.002000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"chain":{"type":"string"},"block":{"type":"number"},"observedAt":{"type":"string"},"current":{"type":"object","description":"baseFeeGwei, congestion, gasUsedRatio"},"recent":{"type":"object","description":"medianGwei, p10Gwei, p90Gwei, volatility, blocks"},"forecast":{"type":"object","description":"centerGwei, lowGwei, highGwei, targetBlock, interval"}}},"example":{"success":true,"chain":"base-mainnet","block":24881003,"observedAt":"2026-07-30T04:12:00.000Z","current":{"baseFeeGwei":0.0142,"congestion":"calm","gasUsedRatio":0.31},"recent":{"medianGwei":0.0138,"p10Gwei":0.0119,"p90Gwei":0.0181,"volatility":0.041,"blocks":300},"forecast":{"horizonMinutes":5,"targetBlock":24881153,"centerGwei":0.0139,"lowGwei":0.0106,"highGwei":0.0182,"interval":0.8,"method":"mean-reverting log random walk on realised block volatility"}}}}},"402":{"description":"Payment required. Terms are in the PAYMENT-REQUIRED response header."}},"parameters":[{"name":"horizonMinutes","in":"query","required":false,"description":"Forecast horizon in minutes (1-60, default 5)","schema":{"type":"integer","minimum":1,"maximum":60,"default":5}}]}},"/api/v1/gas/decision":{"post":{"operationId":"gasDecision","summary":"Journal a gas-timing decision and receive an auditable decision_id","tags":["Data"],"description":"Records an agent decision (execute now, or wait) against a fresh forecast snapshot and returns a decision_id plus the block at which the outcome becomes checkable. Nothing is predicted here beyond the snapshot: this is a tamper-evident journal entry so the agent can later prove what it knew and what it chose.","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.003000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"decisionId":{"type":"string"},"stance":{"type":"string"},"recordedAt":{"type":"string"},"auditableAt":{"type":"string"},"targetBlock":{"type":"number"},"snapshot":{"type":"object"},"auditUrl":{"type":"string"}}},"example":{"success":true,"decisionId":"7c1f9a2b4d6e8f0a1b2c3d4e5f607182","stance":"wait","recordedAt":"2026-07-30T04:12:00.000Z","auditableAt":"2026-07-30T04:27:00.000Z","targetBlock":24881453,"snapshot":{"baseFeeGwei":0.0142,"lowGwei":0.0106,"highGwei":0.0182},"auditUrl":"https://lotusnetworkapi.com/api/v1/gas/audit/7c1f9a2b4d6e8f0a1b2c3d4e5f607182"}}}},"402":{"description":"Payment required. Terms are in the PAYMENT-REQUIRED response header."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"stance":{"type":"string","enum":["execute","wait"],"description":"The agent decision being recorded"},"horizonMinutes":{"type":"integer","minimum":1,"maximum":60,"default":5},"maxFeeGwei":{"type":"number","description":"Optional ceiling the agent was willing to pay"},"note":{"type":"string","description":"Optional free-text rationale, max 500 chars"}},"required":["stance"]},"example":{"stance":"wait","horizonMinutes":15,"maxFeeGwei":0.012}}}}}},"/api/v1/gas/audit/{decisionId}":{"get":{"operationId":"gasAudit","summary":"Verify a journalled decision against what gas actually did","tags":["Data"],"description":"Resolves a decision_id against on-chain reality: what the base fee actually was at the target block, whether the forecast range contained it, and whether the recorded stance turned out cheaper than the alternative. Returns pending if the target block has not been reached yet. This is the verification half of the loop.","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.002000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"decisionId":{"type":"string"},"status":{"type":"string","enum":["resolved","pending"]},"stance":{"type":"string"},"forecast":{"type":"object"},"actual":{"type":"object"},"rangeContainedActual":{"type":"boolean"},"changePct":{"type":"number"},"stanceOutcome":{"type":"string","enum":["favourable","unfavourable","neutral"]},"explanation":{"type":"string"}}},"example":{"success":true,"decisionId":"7c1f9a2b4d6e8f0a1b2c3d4e5f607182","status":"resolved","stance":"wait","forecast":{"lowGwei":0.0106,"centerGwei":0.0139,"highGwei":0.0182},"actual":{"block":24881453,"baseFeeGwei":0.0121,"observedAt":"2026-07-30T04:27:04.000Z"},"rangeContainedActual":true,"changePct":-14.8,"stanceOutcome":"favourable","explanation":"Base fee fell 14.8% over the horizon, so waiting was cheaper than executing."}}}},"402":{"description":"Payment required. Terms are in the PAYMENT-REQUIRED response header."}},"parameters":[{"name":"decisionId","in":"path","required":true,"description":"The decision_id returned by /gas/decision","schema":{"type":"string"}}]}},"/api/v1/patron/pledge/supporter":{"post":{"operationId":"pledgeSupporter","summary":"Pledge as a Lotus Supporter (1 month)","tags":["Patron"],"description":"Recurring monthly pledge of $5 USDC supporting Lotus Network. Grants Lotus Supporter status for 30 days. This is a support tier, not a verified safety or behavior score.","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"5.000000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"wallet":{"type":"string"},"tier":{"type":"string"},"expiresAt":{"type":"string"}}},"example":{"success":true,"wallet":"0x...","tier":"supporter","tierLabel":"Lotus Supporter","pledgedAt":"2026-08-13T00:00:00.000Z","expiresAt":"2026-09-12T00:00:00.000Z"}}}},"402":{"description":"Payment required. Terms are in the PAYMENT-REQUIRED response header."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"walletAddress":{"type":"string"}}},"example":{"walletAddress":"0xYourWalletAddress"}}}}}},"/api/v1/patron/pledge/advocate":{"post":{"operationId":"pledgeAdvocate","summary":"Pledge as a Lotus Advocate (1 month)","tags":["Patron"],"description":"Recurring monthly pledge of $15 USDC supporting Lotus Network. Grants Lotus Advocate status for 30 days. This is a support tier, not a verified safety or behavior score.","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"15.000000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"wallet":{"type":"string"},"tier":{"type":"string"},"expiresAt":{"type":"string"}}},"example":{"success":true,"wallet":"0x...","tier":"advocate","tierLabel":"Lotus Advocate","pledgedAt":"2026-08-13T00:00:00.000Z","expiresAt":"2026-09-12T00:00:00.000Z"}}}},"402":{"description":"Payment required. Terms are in the PAYMENT-REQUIRED response header."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"walletAddress":{"type":"string"}}},"example":{"walletAddress":"0xYourWalletAddress"}}}}}},"/api/v1/patron/pledge/champion":{"post":{"operationId":"pledgeChampion","summary":"Pledge as a Lotus Champion (1 month)","tags":["Patron"],"description":"Recurring monthly pledge of $50 USDC supporting Lotus Network. Grants Lotus Champion status for 30 days. This is a support tier, not a verified safety or behavior score.","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"50.000000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"wallet":{"type":"string"},"tier":{"type":"string"},"expiresAt":{"type":"string"}}},"example":{"success":true,"wallet":"0x...","tier":"champion","tierLabel":"Lotus Champion","pledgedAt":"2026-08-13T00:00:00.000Z","expiresAt":"2026-09-12T00:00:00.000Z"}}}},"402":{"description":"Payment required. Terms are in the PAYMENT-REQUIRED response header."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"walletAddress":{"type":"string"}}},"example":{"walletAddress":"0xYourWalletAddress"}}}}}}}}