{"openapi":"3.0.3","info":{"title":"PicoPayd QR Code Service","version":"0.1.0","description":"QR code generation service with support for custom colors, sizes, error correction levels, and logo overlays.\n\nAll paid endpoints use the **x402 payment protocol** (HTTP 402). When calling a paid endpoint without payment, you receive a `402 Payment Required` response. Submit payment on the Base Sepolia network and retry the request with the `X-Payment` header.\n\n**Pricing:**\n- QR code generation (≤500px): $0.001 per request\n- QR code generation (>500px): $0.01 per request\n- QR code with logo: $0.01 per request\n- QR data validation: Free","contact":{"name":"PicoPayd Support"}},"servers":[{"url":"https://qrcode.picopayd.codefission.co.uk","description":"Production server"},{"url":"http://localhost:8787","description":"Local development server"}],"tags":[{"name":"QR Code","description":"QR code generation endpoints"},{"name":"Health","description":"Service health monitoring"}],"paths":{"/health":{"get":{"tags":["Health"],"summary":"Health check","description":"Returns service health status. Free endpoint, no payment required.","operationId":"getHealth","responses":{"200":{"description":"Service is healthy","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"healthy"},"service":{"type":"string","example":"qr-code-service"},"version":{"type":"string","example":"0.1.0"},"timestamp":{"type":"string","format":"date-time"}}}}}}}}},"/api/qrcode":{"post":{"tags":["QR Code"],"summary":"Generate QR code","description":"Generate a QR code from text, URLs, or any data up to 2953 characters. Output as PNG (base64), SVG, or UTF-8 text art. Supports custom sizes, four error correction levels, adjustable margins, and custom foreground/background colors.\n\n**Paid endpoint** — requires x402 payment on Base Sepolia network.\n- Price: $0.001 for sizes ≤500px\n- Price: $0.01 for sizes >500px","operationId":"generateQRCode","x-payment":{"price":"$0.001–$0.01","network":"base-sepolia","protocol":"x402"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"string","minLength":1,"maxLength":2953,"description":"Text, URL, or data to encode in the QR code","example":"https://example.com"},"format":{"type":"string","enum":["png","svg","utf8"],"default":"png","description":"Output format (default: png)"},"size":{"type":"integer","minimum":100,"maximum":2000,"default":300,"description":"Size in pixels — width and height (default: 300)"},"errorCorrectionLevel":{"type":"string","enum":["L","M","Q","H"],"default":"H","description":"Error correction capacity: L=7%, M=15%, Q=25%, H=30% (default: H)"},"margin":{"type":"integer","minimum":0,"maximum":10,"default":4,"description":"Margin around QR code in modules (default: 4)"},"color":{"type":"object","description":"Custom module colors","properties":{"dark":{"type":"string","description":"Dark module color as hex (default: #000000)","example":"#000000","pattern":"^#[0-9a-fA-F]{6}$"},"light":{"type":"string","description":"Light module color as hex (default: #ffffff)","example":"#ffffff","pattern":"^#[0-9a-fA-F]{6}$"}}}}},"examples":{"url":{"summary":"URL QR code (PNG, 300px)","value":{"data":"https://example.com","format":"png","size":300,"errorCorrectionLevel":"H"}},"svg":{"summary":"SVG QR code","value":{"data":"Hello, World!","format":"svg","size":400}},"colored":{"summary":"Colored QR code","value":{"data":"https://example.com","format":"png","size":300,"color":{"dark":"#1a1a2e","light":"#f0f0f0"}}}}}}},"responses":{"200":{"description":"Generated QR code","content":{"application/json":{"schema":{"type":"object","properties":{"qrCode":{"type":"string","description":"Generated QR code — base64 PNG, SVG string, or UTF-8 text art"},"format":{"type":"string","enum":["png","svg","utf8"]},"size":{"type":"integer","description":"Output size in pixels"},"errorCorrectionLevel":{"type":"string","enum":["L","M","Q","H"]},"dataLength":{"type":"integer","description":"Length of the encoded data in characters"}}},"examples":{"png":{"summary":"PNG QR code result","value":{"qrCode":"iVBORw0KGgoAAAANSUhEUgAAA...","format":"png","size":300,"errorCorrectionLevel":"H","dataLength":19}}}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}}}}},"/api/qrcode/logo":{"post":{"tags":["QR Code"],"summary":"Generate QR code with logo","description":"Generate a QR code with a centered logo overlay. Automatically uses high error correction (H) to maintain scannability around the logo. Logo size is configurable as a percentage of the QR code area. Returns a PNG image.\n\n**Paid endpoint** — requires x402 payment on Base Sepolia network. Price: $0.01 per request.","operationId":"generateQRCodeWithLogo","x-payment":{"price":"$0.01","network":"base-sepolia","protocol":"x402"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["data","logoUrl"],"properties":{"data":{"type":"string","minLength":1,"maxLength":2953,"description":"Text or URL to encode","example":"https://example.com"},"logoUrl":{"type":"string","format":"uri","description":"URL of the logo image to overlay on the QR code","example":"https://example.com/logo.png"},"size":{"type":"integer","minimum":200,"maximum":2000,"default":400,"description":"QR code size in pixels (default: 400)"},"logoSize":{"type":"integer","minimum":10,"maximum":30,"default":20,"description":"Logo size as percentage of QR code area (default: 20)"},"errorCorrectionLevel":{"type":"string","enum":["L","M","Q","H"],"default":"H","description":"Error correction level — H recommended for logos (default: H)"}}},"examples":{"branded":{"summary":"Branded QR code","value":{"data":"https://example.com","logoUrl":"https://example.com/logo.png","size":400,"logoSize":20}}}}}},"responses":{"200":{"description":"QR code with logo","content":{"application/json":{"schema":{"type":"object","properties":{"qrCode":{"type":"string","description":"Base64-encoded PNG QR code with logo overlay"},"format":{"type":"string","example":"png"},"size":{"type":"integer"},"logoUrl":{"type":"string","format":"uri"},"logoSizePercent":{"type":"integer","description":"Actual logo size used as % of QR area"}}}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}}}}},"/api/qrcode/validate":{"post":{"tags":["QR Code"],"summary":"Validate QR data","description":"Validate data before encoding to a QR code. Checks data length limits, detects URLs, and recommends optimal QR code size. Free endpoint, no payment required.","operationId":"validateQRData","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"string","minLength":1,"description":"Text or URL to validate for QR encoding","example":"https://example.com"}}}}}},"responses":{"200":{"description":"QR data validation result","content":{"application/json":{"schema":{"type":"object","properties":{"valid":{"type":"boolean","description":"Whether data can be encoded in a QR code"},"dataLength":{"type":"integer","description":"Character count of the data"},"isUrl":{"type":"boolean","description":"Whether the data appears to be a URL"},"recommendedSize":{"type":"integer","description":"Recommended QR code size in pixels based on data complexity"},"maxCapacity":{"type":"integer","description":"Maximum character capacity (2953)"},"remainingCapacity":{"type":"integer","description":"Remaining character capacity"}}},"examples":{"url":{"summary":"URL validation result","value":{"valid":true,"dataLength":19,"isUrl":true,"recommendedSize":200,"maxCapacity":2953,"remainingCapacity":2934}}}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"code":{"type":"string","description":"Error code"}}},"PaymentRequired":{"type":"object","description":"x402 payment required response. Pay using the Base Sepolia network and retry with X-Payment header.","properties":{"error":{"type":"string","example":"Payment required"},"accepts":{"type":"array","items":{"type":"object","properties":{"scheme":{"type":"string","example":"exact"},"network":{"type":"string","example":"base-sepolia"},"amount":{"type":"string","example":"1000"},"asset":{"type":"string","example":"USDC"}}}}}}}}}