{"openapi":"3.1.0","info":{"title":"Shieldz API","version":"1.0.0","description":"Non-custodial crypto payments. Create invoices, send buyers to a hosted checkout, and reconcile via signed webhooks. Funds settle straight to the merchant's own wallet, Shieldz only ever holds a public key.","contact":{"name":"Shieldz","url":"https://shieldz.cash","email":"support@shieldz.cash"},"license":{"name":"Proprietary"}},"servers":[{"url":"https://shieldz.cash/api/v1"}],"security":[{"bearerAuth":[]}],"paths":{"/invoices":{"post":{"operationId":"createInvoice","summary":"Create an invoice","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceCreate"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"}}},"get":{"operationId":"listInvoices","summary":"List invoices (newest first)","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"starting_after","in":"query","schema":{"type":"string"},"description":"Cursor: a public invoice id from a previous page."},{"name":"status","in":"query","schema":{"$ref":"#/components/schemas/InvoiceStatus"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Invoice"}},"has_more":{"type":"boolean"}}}}}}}}},"/invoices/{id}":{"get":{"operationId":"getInvoice","summary":"Retrieve an invoice by its public id","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"404":{"$ref":"#/components/responses/Error"}}}}},"webhooks":{"invoice.paid":{"post":{"summary":"Sent when an invoice is paid. Verify the X-Shieldz-Signature (HMAC-SHA256 over `${t}.${rawBody}`).","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"Acknowledged"}}}},"invoice.failed":{"post":{"summary":"Sent when a payment fails or is refunded.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"Acknowledged"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key: sk_live_… or sk_test_…"}},"responses":{"Error":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"InvoiceStatus":{"type":"string","enum":["pending","paid","expired","failed"]},"InvoiceCreate":{"type":"object","required":["amount_usd_cents"],"properties":{"amount_usd_cents":{"type":"integer","minimum":100,"maximum":10000000,"description":"Amount in USD cents."},"memo":{"type":"string"},"customer_email":{"type":"string","format":"email"},"expires_in_seconds":{"type":"integer","minimum":300,"maximum":86400,"default":1800},"idempotency_key":{"type":"string","description":"Replaying the same key returns the original invoice."},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary JSON, echoed back on webhooks."},"settlement":{"$ref":"#/components/schemas/Settlement"}}},"Settlement":{"type":"object","properties":{"chain":{"type":"string","example":"BASE"},"asset":{"type":"string","example":"USDC"},"address":{"type":"string"}}},"Invoice":{"type":"object","properties":{"id":{"type":"string"},"object":{"const":"invoice"},"amount_usd_cents":{"type":"integer"},"memo":{"type":["string","null"]},"settlement":{"$ref":"#/components/schemas/Settlement"},"status":{"$ref":"#/components/schemas/InvoiceStatus"},"pay_url":{"type":"string","format":"uri"},"expires_at":{"type":"integer","description":"Unix milliseconds."},"paid_at":{"type":["integer","null"]},"mode":{"type":"string","enum":["live","test"]},"metadata":{}}},"WebhookEvent":{"type":"object","properties":{"type":{"type":"string","example":"invoice.paid"},"created":{"type":"integer"},"data":{"type":"object","properties":{"invoice":{"$ref":"#/components/schemas/Invoice"}}}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}}}}}}}}