{"openapi":"3.1.0","info":{"title":"Fauzec public HTTP surface","version":"0.1.0"},"components":{"schemas":{"NetworkResponse":{"type":"object","properties":{"network":{"type":"string","enum":["testnet","mainnet"],"description":"Configured network. Mainnet is rejected in v0."},"supported_address_kinds":{"type":"array","items":{"type":"string","enum":["unified","sapling","transparent"]}},"funding_receiver_kinds":{"type":"array","items":{"type":"string","enum":["unified","sapling","transparent"]}},"captcha_mode":{"type":"string","enum":["launch_blocked","local_test","turnstile"]},"turnstile_site_key":{"type":"string"},"drip_zat":{"type":"integer","minimum":0},"max_amount_zat_per_claim":{"type":"integer","minimum":0},"address_cooldown_hours":{"type":"integer","minimum":0},"support_url":{"type":"string","format":"uri"},"source_url":{"type":"string","format":"uri"},"explorer_tx_url_template":{"type":"string","minLength":1},"sibling_network_origin":{"type":"string","format":"uri"},"fallback_faucets":{"type":"array","items":{"$ref":"#/components/schemas/FallbackFaucet"}}},"required":["network","supported_address_kinds","funding_receiver_kinds","captcha_mode","drip_zat","max_amount_zat_per_claim","address_cooldown_hours","support_url","fallback_faucets"]},"FallbackFaucet":{"type":"object","properties":{"name":{"type":"string","minLength":1},"url":{"type":"string","format":"uri"}},"required":["name","url"]},"FailureResponse":{"type":"object","properties":{"request_id":{"type":"string"},"network":{"type":"string","enum":["testnet","mainnet"],"description":"Configured network. Mainnet is rejected in v0."},"error_code":{"type":"string","enum":["malformed_request","malformed_address","network_mismatch","unsupported_address_kind","memo_unsupported_for_transparent","captcha_required","on_abuse_list","address_on_cooldown","ip_on_cooldown","faucet_dry","wallet_unavailable","wallet_operation_failed","node_unavailable","claim_not_found","runtime_unavailable","launch_blocked"]}},"required":["error_code"]},"HealthResponse":{"type":"object","properties":{"network":{"type":"string","enum":["testnet","mainnet"],"description":"Configured network. Mainnet is rejected in v0."},"is_live":{"type":"boolean","enum":[true]}},"required":["network","is_live"]},"ClaimResponse":{"type":"object","properties":{"request_id":{"type":"string"},"network":{"type":"string","enum":["testnet","mainnet"],"description":"Configured network. Mainnet is rejected in v0."},"state":{"type":"string","enum":["pending","submitted","confirmed","failed"]},"outcome":{"type":"string","enum":["accepted","refused","failed"]},"txid":{"type":"string"},"next_eligible_at_ms":{"type":"integer","minimum":0},"error_code":{"type":"string","enum":["malformed_request","malformed_address","network_mismatch","unsupported_address_kind","memo_unsupported_for_transparent","captcha_required","on_abuse_list","address_on_cooldown","ip_on_cooldown","faucet_dry","wallet_unavailable","wallet_operation_failed","node_unavailable","claim_not_found","runtime_unavailable","launch_blocked"]},"refusal_cause":{"type":"string","enum":["launch_blocked","captcha_required","address_on_cooldown","ip_on_cooldown","on_abuse_list","faucet_dry","network_mismatch","malformed_address","unsupported_address_kind","memo_unsupported_for_transparent"]},"claim_amount_zat":{"type":"integer","minimum":0},"claim_amount_clamped":{"type":"boolean"}},"required":["request_id","network","state"]},"ClaimRequest":{"type":"object","properties":{"network":{"type":"string","enum":["testnet","mainnet"],"description":"Configured network. Mainnet is rejected in v0."},"address":{"type":"string","minLength":1},"amount_zat":{"type":"integer","minimum":0},"memo":{"type":"string","minLength":1},"captcha_token":{"type":"string","minLength":1},"request_id":{"type":"string","minLength":1}},"required":["network","address","captcha_token"]},"ClaimStatusResponse":{"type":"object","properties":{"request_id":{"type":"string"},"network":{"type":"string","enum":["testnet","mainnet"],"description":"Configured network. Mainnet is rejected in v0."},"address":{"type":"string"},"address_kind":{"type":"string","enum":["unified","sapling","transparent"]},"privacy_policy":{"type":"string","enum":["full_privacy","allow_revealed_recipients"]},"amount_zat":{"type":"integer","minimum":0},"memo":{"type":"string"},"state":{"type":"string","enum":["pending","submitted","confirmed","failed"]},"outcome":{"type":"string","enum":["accepted","refused","failed"]},"txid":{"type":"string"},"confirmed_height":{"type":"integer","minimum":0},"next_eligible_at_ms":{"type":"integer","minimum":0},"error_code":{"type":"string","enum":["malformed_request","malformed_address","network_mismatch","unsupported_address_kind","memo_unsupported_for_transparent","captcha_required","on_abuse_list","address_on_cooldown","ip_on_cooldown","faucet_dry","wallet_unavailable","wallet_operation_failed","node_unavailable","claim_not_found","runtime_unavailable","launch_blocked"]},"refusal_cause":{"type":"string","enum":["launch_blocked","captcha_required","address_on_cooldown","ip_on_cooldown","on_abuse_list","faucet_dry","network_mismatch","malformed_address","unsupported_address_kind","memo_unsupported_for_transparent"]},"failure_reason":{"type":"string"}},"required":["request_id","network","address","address_kind","privacy_policy","amount_zat","state"]},"ListDonationsResponse":{"type":"object","properties":{"network":{"type":"string","enum":["testnet","mainnet"],"description":"Configured network. Mainnet is rejected in v0."},"window":{"type":"string","enum":["all_time","last_30_days","last_7_days"]},"entries":{"type":"array","items":{"$ref":"#/components/schemas/DonationEntry"}}},"required":["network","window","entries"]},"DonationEntry":{"type":"object","properties":{"txid":{"type":"string","minLength":1},"outindex":{"type":"integer","minimum":0},"amount_zat":{"type":"integer","minimum":0},"received_at_ms":{"type":"integer","minimum":0},"observed_height":{"type":"integer","minimum":0},"memo_text":{"type":"string"}},"required":["txid","outindex","amount_zat","received_at_ms","observed_height"]},"DonationsSummaryResponse":{"type":"object","properties":{"network":{"type":"string","enum":["testnet","mainnet"],"description":"Configured network. Mainnet is rejected in v0."},"total_donated_zat_all_time":{"type":"integer","minimum":0},"total_donated_zat_last_30_days":{"type":"integer","minimum":0},"total_donated_zat_last_7_days":{"type":"integer","minimum":0},"donation_count_all_time":{"type":"integer","minimum":0},"donation_address":{"type":"string"},"confirmed_balance_zat":{"type":"integer","minimum":0}},"required":["network","total_donated_zat_all_time","total_donated_zat_last_30_days","total_donated_zat_last_7_days","donation_count_all_time","donation_address","confirmed_balance_zat"]}},"parameters":{}},"paths":{"/api/v1/network":{"get":{"operationId":"readNetwork","summary":"Read the public-tier network configuration.","responses":{"200":{"description":"Active network and supported address kinds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NetworkResponse"}}}},"503":{"description":"Runtime unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureResponse"}}}}}}},"/api/v1/healthz":{"get":{"operationId":"readHealth","summary":"Read public-tier process liveness.","responses":{"200":{"description":"Public-tier process liveness.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}},"503":{"description":"Runtime unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureResponse"}}}}}}},"/api/v1/claim":{"post":{"operationId":"submitClaim","summary":"Submit a faucet claim.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimRequest"}}}},"responses":{"200":{"description":"Claim accepted, refused, or already recorded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimResponse"}}}},"400":{"description":"Malformed public claim request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimResponse"}}}},"403":{"description":"Captcha or abuse-list refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimResponse"}}}},"404":{"description":"Claim not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimResponse"}}}},"409":{"description":"Recipient address cooldown.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimResponse"}}}},"429":{"description":"Requester IP cooldown.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimResponse"}}}},"503":{"description":"Runtime or upstream dependency unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimResponse"}}}}}}},"/api/v1/status/{network}/{request_id}":{"get":{"operationId":"readClaimStatus","summary":"Read the current state of a submitted claim.","parameters":[{"schema":{"type":"string","enum":["testnet","mainnet"],"description":"Configured network. Mainnet is rejected in v0."},"required":true,"description":"Configured network. Mainnet is rejected in v0.","name":"network","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"request_id","in":"path"}],"responses":{"200":{"description":"Current claim state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimStatusResponse"}}}},"400":{"description":"Malformed status request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureResponse"}}}},"404":{"description":"Claim not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureResponse"}}}},"503":{"description":"Runtime unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureResponse"}}}}}}},"/api/v1/donations":{"get":{"operationId":"listDonations","summary":"List top donations within a time window.","parameters":[{"schema":{"type":"string","enum":["all_time","last_30_days","last_7_days"]},"required":false,"name":"window","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":50},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Top donations ordered by amount, descending.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListDonationsResponse"}}}},"503":{"description":"Runtime unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureResponse"}}}}}}},"/api/v1/donations/summary":{"get":{"operationId":"readDonationsSummary","summary":"Aggregate donation statistics and the public donation address.","responses":{"200":{"description":"Aggregate donation statistics for the active network.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DonationsSummaryResponse"}}}},"503":{"description":"Runtime unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureResponse"}}}}}}}}}