{"openapi":"3.1.0","info":{"title":"VNX hosted invoice gateway","version":"1.0.0","description":"Private durable invoice storage, verified factory deposits and wallet-authorized mainnet payments. Administrative operations require a signed secure cookie session. Customer checkout is public; merchant integrations use a separate Bearer credential. All amounts remain exact decimal or integer strings. Factory deployment and verification are required before payments."},"servers":[{"url":"/","description":"This HTTPS gateway"}],"tags":[{"name":"Invoices"},{"name":"Customer payment"},{"name":"Merchant settings"},{"name":"Merchant vault"},{"name":"Factory deployment"},{"name":"Merchant conversion"},{"name":"Merchant integration"},{"name":"Operations"}],"paths":{"/api/admin/settings":{"get":{"operationId":"getMerchantSettings","tags":["Merchant settings"],"summary":"Read persisted merchant settings","responses":{"200":{"description":"Verified local API response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Settings"}}}},"401":{"description":"Administrative sign-in is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid amount, address, policy or transaction request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Chain proof unavailable or the required factory is not verified yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"AdminSession":[]}]},"post":{"operationId":"saveMerchantSettings","tags":["Merchant settings"],"summary":"Save VNX or BNB payout destination, tolerance and independently verified factory","responses":{"200":{"description":"Verified local API response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Settings"}}}},"401":{"description":"Administrative sign-in is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"VAULT_OWNER_ALREADY_SET: first-time setup cannot replace an owner already saved, including one saved concurrently.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid amount, address, policy or transaction request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Chain proof unavailable or the required factory is not verified yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Origin","in":"header","required":true,"schema":{"type":"string","example":"https://dan-cash.com"},"description":"Must exactly match the configured HTTPS gateway origin."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettingsInput"}}}},"description":"Customers always pay VNX on BNB Smart Chain. settlementMode VAULT requires an explicit vaultOwner and receives VNX into that owner’s deterministic merchant vault. It forces payoutAsset VNX; the owner can later withdraw VNX or convert a selected balance to BNB. DIRECT retains the original VNX forwarding or atomic BNB payout modes. BSC is the network, not a separate payout asset. Changes apply to future invoice snapshots and never redirect an existing invoice or change a recorded vault owner. First-time setup sends initializeVaultOwner true with an explicit vaultOwner and VAULT settlement mode; an atomic check rejects an already saved owner with 409 VAULT_OWNER_ALREADY_SET, including concurrent setup attempts. Intentional owner edits omit the initialization guard. Saving a verified factory activates drafts with their original policies. An unverified factory is rejected. This endpoint does not deploy contracts.","security":[{"AdminSession":[]}]}},"/api/admin/invoices":{"get":{"operationId":"listInvoices","tags":["Invoices"],"summary":"List local durable invoice records","responses":{"200":{"description":"Verified local API response.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Invoice"}}}}},"401":{"description":"Administrative sign-in is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid amount, address, policy or transaction request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Chain proof unavailable or the required factory is not verified yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"AdminSession":[]}]},"post":{"operationId":"createInvoice","tags":["Invoices"],"summary":"Create an invoice for an exact VNX amount","responses":{"200":{"description":"Original invoice returned for an idempotent retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"201":{"description":"Invoice created and stored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"401":{"description":"Administrative sign-in is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Idempotency key already belongs to another request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid amount.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Fresh chain proof unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Origin","in":"header","required":true,"schema":{"type":"string","example":"https://dan-cash.com"},"description":"Must exactly match the configured HTTPS gateway origin."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":128},"description":"Retry the same canonical request with the same key to receive the original invoice. A changed request returns 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceInput"}}}},"description":"Snapshots the VNX payer amount, settlement mode, vault owner or direct payout destination and tolerance, obtains a matching finalized chain block, and stores an opaque invoice UUID. VAULT invoices forward to the owner-bound vault and become PAID when actual VNX vault receipt is finalized. Without a verified factory this creates a nonpayable draft with no deposit or vault address.","security":[{"AdminSession":[]}]}},"/api/invoices/{invoiceId}":{"get":{"operationId":"readInvoice","tags":["Invoices"],"summary":"Read server-derived payment status and accumulated credits","responses":{"200":{"description":"Verified local API response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"422":{"description":"Invalid amount, address, policy or transaction request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Chain proof unavailable or the required factory is not verified yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"invoiceId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Opaque UUID returned when the invoice is created."}],"description":"Only finalized matching InvoicePaid (VNX) or InvoicePaidBnb (BNB) events from the verified factory credit the matching payout policy and destination. VNX payouts credit merchant net VNX receipt; BNB payouts credit the net VNX input actually deposited for conversion and record BNB output separately in creditedBnbAmount. PENDING and PARTIALLY_PAID do not fulfil payment. PAID is terminal; later excess is retained separately for review."}},"/api/invoices/{invoiceId}/config":{"get":{"operationId":"readInvoiceConfig","tags":["Customer payment"],"summary":"Read immutable invoice wallet policy","responses":{"200":{"description":"Verified local API response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceConfig"}}}},"422":{"description":"Invalid amount, address, policy or transaction request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Chain proof unavailable or the required factory is not verified yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"invoiceId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Opaque UUID returned when the invoice is created."}]}},"/api/invoices/{invoiceId}/quote":{"get":{"operationId":"quoteInvoicePayment","tags":["Customer payment"],"summary":"Read current token tax, payer balance and factory allowance","responses":{"200":{"description":"Verified local API response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Quote"}}}},"422":{"description":"Invalid amount, address, policy or transaction request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Chain proof unavailable or the required factory is not verified yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"invoiceId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Opaque UUID returned when the invoice is created."},{"name":"account","in":"query","required":false,"schema":{"$ref":"#/components/schemas/Address"},"description":"Connected paying wallet, or configured receiving wallet for merchant operations."}],"description":"Read-only chain checks. Requires a verified factory. Customers always pay VNX. A VNX invoice forwards the token to the merchant; a BNB invoice quotes an atomic VNX-to-BNB swap to the immutable BNB destination. Current expectedOut and minOut describe BNB output only for BNB invoices."}},"/api/invoices/{invoiceId}/prepare":{"post":{"operationId":"prepareInvoicePayment","tags":["Customer payment"],"summary":"Prepare an exact approval or factory payment for the customer wallet","responses":{"200":{"description":"Verified local API response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreparedTransaction"}}}},"422":{"description":"Invalid amount, address, policy or transaction request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Chain proof unavailable or the required factory is not verified yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"invoiceId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Opaque UUID returned when the invoice is created."},{"name":"Origin","in":"header","required":true,"schema":{"type":"string","example":"https://dan-cash.com"},"description":"Must exactly match the configured HTTPS gateway origin."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"account":{"$ref":"#/components/schemas/Address"},"action":{"type":"string","enum":["approve","pay"]}},"required":["account","action"]}}}},"description":"Returns unsigned calldata after independently verifying the factory, predicted deposit, amount, allowance, simulation and gas budget. Approval and payment each require a separate customer wallet authorization. The server never submits either transaction."}},"/api/invoices/{invoiceId}/receipt":{"get":{"operationId":"verifyInvoicePaymentReceipt","tags":["Customer payment"],"summary":"Verify an approval or finalized forwarded payment","responses":{"200":{"description":"Verified local API response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Receipt"}}}},"422":{"description":"Invalid amount, address, policy or transaction request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Chain proof unavailable or the required factory is not verified yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"invoiceId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Opaque UUID returned when the invoice is created."},{"name":"hash","in":"query","required":true,"schema":{"$ref":"#/components/schemas/TransactionHash"}},{"name":"account","in":"query","required":true,"schema":{"$ref":"#/components/schemas/Address"},"description":"Connected paying wallet, or configured receiving wallet for merchant operations."},{"name":"action","in":"query","required":true,"schema":{"type":"string","enum":["approve","pay"]}}],"description":"Checks exact wallet calldata and canonical chain proofs. A successful pay proof reconciles actual merchant receipts into the local ledger and includes invoiceStatus. Fulfilment depends on the invoice status, not merely a successful transaction."}},"/api/invoices/{invoiceId}/transactions":{"post":{"operationId":"registerInvoiceTransaction","tags":["Invoices"],"summary":"Request independent verification of a transaction hash","responses":{"200":{"description":"Verified local API response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"invoice":{"$ref":"#/components/schemas/Invoice"},"transactionStatus":{"type":"string","enum":["pending","reverted","verified"]}},"required":["invoice","transactionStatus"]}}}},"422":{"description":"Invalid amount, address, policy or transaction request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Chain proof unavailable or the required factory is not verified yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"invoiceId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Opaque UUID returned when the invoice is created."},{"name":"Origin","in":"header","required":true,"schema":{"type":"string","example":"https://dan-cash.com"},"description":"Must exactly match the configured HTTPS gateway origin."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"hash":{"$ref":"#/components/schemas/TransactionHash"}},"required":["hash"]}}}},"description":"Browser amounts and PAID claims are not accepted. Only matching finalized factory events are credited. Global transaction-hash/log-index deduplication prevents double credit."}},"/api/invoices/{invoiceId}/qr.svg":{"get":{"operationId":"readInvoiceQr","tags":["Invoices"],"summary":"Generate an SVG QR for the opaque invoice checkout link","responses":{"200":{"description":"Actual QR SVG generated by the installed QR encoder.","content":{"image/svg+xml":{"schema":{"type":"string"}}}},"404":{"description":"Invoice not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"invoiceId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Opaque UUID returned when the invoice is created."}],"description":"Encodes this local server origin plus /?invoice=UUID. A draft QR opens a nonpayable invoice. localhost is available on this computer; it is not a public mobile checkout URL."}},"/api/invoices/{invoiceId}/forward/prepare":{"post":{"operationId":"prepareDirectDepositForwarding","tags":["Customer payment"],"summary":"Prepare recovery of directly deposited VNX under the immutable payout policy","responses":{"200":{"description":"Verified local API response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreparedTransaction"}}}},"422":{"description":"Invalid amount, address, policy or transaction request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Chain proof unavailable or the required factory is not verified yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"invoiceId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Opaque UUID returned when the invoice is created."},{"name":"Origin","in":"header","required":true,"schema":{"type":"string","example":"https://dan-cash.com"},"description":"Must exactly match the configured HTTPS gateway origin."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"account":{"$ref":"#/components/schemas/Address"},"action":{"type":"string","const":"forward"}},"required":["account","action"]}}}},"description":"A direct ERC-20 transfer to the unique deposit does not execute forwarding or conversion. In VNX mode any wallet may pay gas to forward only to the immutable recipient. In BNB mode only the immutable BNB recipient may authorize recovery and conversion, with a fresh minimum-output quote and deadline. The caller cannot choose another recipient. Unsigned calldata is returned after simulation."}},"/api/invoices/{invoiceId}/forward/receipt":{"get":{"operationId":"verifyDirectDepositForwarding","tags":["Customer payment"],"summary":"Verify actual merchant receipt from a direct-deposit forwarding transaction","responses":{"200":{"description":"Verified local API response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Receipt"}}}},"422":{"description":"Invalid amount, address, policy or transaction request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Chain proof unavailable or the required factory is not verified yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"invoiceId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Opaque UUID returned when the invoice is created."},{"name":"hash","in":"query","required":true,"schema":{"$ref":"#/components/schemas/TransactionHash"}},{"name":"account","in":"query","required":true,"schema":{"$ref":"#/components/schemas/Address"},"description":"Connected paying wallet, or configured receiving wallet for merchant operations."}],"description":"Only a finalized matching InvoicePaid or InvoicePaidBnb event for the immutable payout policy credits the invoice. A deposit balance by itself is never PAID."}},"/api/admin/factory-artifact":{"get":{"operationId":"readFactoryArtifact","tags":["Factory deployment"],"summary":"Read compiled source metadata, ABI and deployment bytecode","responses":{"200":{"description":"Verified local API response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FactoryArtifact"}}}},"401":{"description":"Administrative sign-in is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid amount, address, policy or transaction request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Chain proof unavailable or the required factory is not verified yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Returns the reviewed artifact for BNB Smart Chain. This endpoint does not deploy or sign anything.","security":[{"AdminSession":[]}]}},"/api/admin/vault":{"get":{"operationId":"readMerchantVault","tags":["Merchant vault"],"summary":"Read verified vault balance, withdrawal quote and persistent history","responses":{"200":{"description":"Verified local API response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VaultOverview"}}}},"401":{"description":"Administrative sign-in is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid amount, address, policy or transaction request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Chain proof unavailable or the required factory is not verified yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"factoryAddress","in":"query","required":false,"schema":{"$ref":"#/components/schemas/Address"},"description":"Historical vault factory. Supply together with owner; the pair must already be registered in the ledger."},{"name":"owner","in":"query","required":false,"schema":{"$ref":"#/components/schemas/Address"},"description":"Immutable owner of the selected current or historical merchant vault."},{"name":"account","in":"query","required":false,"schema":{"$ref":"#/components/schemas/Address"},"description":"Connected paying wallet, or configured receiving wallet for merchant operations."},{"name":"action","in":"query","required":false,"schema":{"type":"string","enum":["withdrawVnx","withdrawBnb"]}},{"name":"amount","in":"query","required":false,"schema":{"$ref":"#/components/schemas/DecimalAmount"}},{"name":"recipient","in":"query","required":false,"schema":{"$ref":"#/components/schemas/Address"}}],"description":"Read-only access to the current or a registered historical vault. With no configured owner or verified factory, returns ready false without fabricating an address or balance. An optional VNX amount quotes a withdrawal; withdrawBnb includes the live minimum BNB output and deadline. Providing account requires that it matches the immutable vault owner. Withdrawal history is separate from invoice fulfillment credits. Automatic quote refresh uses the authenticated native WebSocket /api/admin/vault/quotes/live with amount, action, recipient and optional factoryAddress/owner context; the selected vault is fixed for that connection.","security":[{"AdminSession":[]}]}},"/api/admin/vault/prepare":{"post":{"operationId":"prepareVaultWithdrawal","tags":["Merchant vault"],"summary":"Prepare an owner-authorized VNX withdrawal or VNX-to-BNB vault withdrawal","responses":{"200":{"description":"Verified local API response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreparedTransaction"}}}},"401":{"description":"Administrative sign-in is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid amount, address, policy or transaction request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Chain proof unavailable or the required factory is not verified yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Origin","in":"header","required":true,"schema":{"type":"string","example":"https://dan-cash.com"},"description":"Must exactly match the configured HTTPS gateway origin."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"account":{"$ref":"#/components/schemas/Address"},"action":{"type":"string","enum":["withdrawVnx","withdrawBnb"]},"amount":{"$ref":"#/components/schemas/DecimalAmount"},"recipient":{"$ref":"#/components/schemas/Address"},"factoryAddress":{"$ref":"#/components/schemas/Address"},"owner":{"$ref":"#/components/schemas/Address"}},"required":["account","action","amount","recipient"]}}}},"description":"The connected account must equal the selected vault’s immutable owner. The selected amount and recipient are bound into unsigned factory calldata after independent chain checks and simulation. withdrawVnx transfers VNX; withdrawBnb converts only the selected VNX amount and sends native BNB to the chosen recipient, with a fresh minimum output and deadline. Optional factoryAddress and owner must be supplied together and identify a registered historical vault. The server neither signs nor sends the transaction.","security":[{"AdminSession":[]}]}},"/api/admin/vault/receipt":{"get":{"operationId":"verifyVaultWithdrawal","tags":["Merchant vault"],"summary":"Verify and record a finalized owner-signed vault withdrawal","responses":{"200":{"description":"Verified local API response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VaultWithdrawalReceipt"}}}},"401":{"description":"Administrative sign-in is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid amount, address, policy or transaction request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Chain proof unavailable or the required factory is not verified yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"factoryAddress","in":"query","required":false,"schema":{"$ref":"#/components/schemas/Address"},"description":"Historical vault factory. Supply together with owner; the pair must already be registered in the ledger."},{"name":"owner","in":"query","required":false,"schema":{"$ref":"#/components/schemas/Address"},"description":"Immutable owner of the selected current or historical merchant vault."},{"name":"hash","in":"query","required":true,"schema":{"$ref":"#/components/schemas/TransactionHash"}},{"name":"account","in":"query","required":true,"schema":{"$ref":"#/components/schemas/Address"},"description":"Connected paying wallet, or configured receiving wallet for merchant operations."},{"name":"action","in":"query","required":true,"schema":{"type":"string","enum":["withdrawVnx","withdrawBnb"]}}],"description":"Verifies the actual transaction calldata, owner signature, canonical finalized receipt and matching vault withdrawal event. Independently verified withdrawals are persisted once per transaction and log index. Recorded factory, owner and vault address remain immutable after settings change. A vault withdrawal never creates or increases an invoice payment credit.","security":[{"AdminSession":[]}]}},"/api/admin/factory/prepare":{"post":{"operationId":"prepareFactoryDeployment","tags":["Factory deployment"],"summary":"Simulate and prepare the gateway factory deployment for a developer or operator wallet","responses":{"200":{"description":"Verified local API response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreparedTransaction"}}}},"401":{"description":"Administrative sign-in is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid amount, address, policy or transaction request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Chain proof unavailable or the required factory is not verified yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Origin","in":"header","required":true,"schema":{"type":"string","example":"https://dan-cash.com"},"description":"Must exactly match the configured HTTPS gateway origin."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"account":{"$ref":"#/components/schemas/Address"}},"required":["account"]}}}},"description":"A developer or gateway operator deploys the shared factory once using a chosen EVM wallet with BNB for gas. The deploying account is independent of the merchant VNX and BNB receiving addresses. The returned unsigned creation transaction has no to address and exactly matches the published bytecode. Deployment requires explicit wallet authorization. The factory has no owner privileges; merchant payout destinations are configured separately and bound to each invoice.","security":[{"AdminSession":[]}]}},"/api/admin/factory/receipt":{"get":{"operationId":"verifyFactoryDeploymentReceipt","tags":["Factory deployment"],"summary":"Verify the deployed factory without saving merchant settings","responses":{"200":{"description":"Verified local API response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Receipt"}}}},"401":{"description":"Administrative sign-in is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid amount, address, policy or transaction request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Chain proof unavailable or the required factory is not verified yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"hash","in":"query","required":true,"schema":{"$ref":"#/components/schemas/TransactionHash"}},{"name":"account","in":"query","required":true,"schema":{"$ref":"#/components/schemas/Address"},"description":"Connected paying wallet, or configured receiving wallet for merchant operations."}],"description":"Read-only verification of the developer or operator creation transaction and runtime hash. After confirmation, register the verified factory address in gateway settings. Merchants can subsequently configure receiving addresses without deploying a separate factory. Existing draft invoices retain their original payout destinations when activated.","security":[{"AdminSession":[]}]}},"/api/admin/config":{"get":{"operationId":"readMerchantConversionConfig","tags":["Merchant conversion"],"summary":"Read conversion policy and current required merchant account","responses":{"200":{"description":"Verified local API response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceConfig"}}}},"401":{"description":"Administrative sign-in is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid amount, address, policy or transaction request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Chain proof unavailable or the required factory is not verified yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"amount","in":"query","required":false,"schema":{"$ref":"#/components/schemas/DecimalAmount"},"description":"Selected VNX amount to convert. Defaults to 10 when omitted; the same amount must be used for config, quote, prepare and receipt."}],"security":[{"AdminSession":[]}]}},"/api/admin/quote":{"get":{"operationId":"quoteMerchantConversion","tags":["Merchant conversion"],"summary":"Quote a merchant-authorized VNX to BNB conversion","responses":{"200":{"description":"Verified local API response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Quote"}}}},"401":{"description":"Administrative sign-in is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid amount, address, policy or transaction request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Chain proof unavailable or the required factory is not verified yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"account","in":"query","required":false,"schema":{"$ref":"#/components/schemas/Address"},"description":"Connected paying wallet, or configured receiving wallet for merchant operations."},{"name":"amount","in":"query","required":false,"schema":{"$ref":"#/components/schemas/DecimalAmount"},"description":"Selected VNX amount to convert. Defaults to 10 when omitted; the same amount must be used for config, quote, prepare and receipt."}],"security":[{"AdminSession":[]}]}},"/api/admin/prepare":{"post":{"operationId":"prepareMerchantConversion","tags":["Merchant conversion"],"summary":"Prepare bounded router approval or conversion to the chosen BNB receiver","responses":{"200":{"description":"Verified local API response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreparedTransaction"}}}},"401":{"description":"Administrative sign-in is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid amount, address, policy or transaction request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Chain proof unavailable or the required factory is not verified yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Origin","in":"header","required":true,"schema":{"type":"string","example":"https://dan-cash.com"},"description":"Must exactly match the configured HTTPS gateway origin."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"account":{"$ref":"#/components/schemas/Address"},"action":{"type":"string","enum":["approve","swap"]},"recipient":{"$ref":"#/components/schemas/Address"},"amount":{"$ref":"#/components/schemas/DecimalAmount"}},"required":["account","action","recipient"]}}}},"description":"The paying account must be the configured receiving wallet. The selected BNB recipient is bound to unsigned calldata. Conversion is a later merchant wallet action.","security":[{"AdminSession":[]}]}},"/api/admin/receipt":{"get":{"operationId":"verifyMerchantConversionReceipt","tags":["Merchant conversion"],"summary":"Verify the merchant conversion and exact BNB destination","responses":{"200":{"description":"Verified local API response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Receipt"}}}},"401":{"description":"Administrative sign-in is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid amount, address, policy or transaction request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Chain proof unavailable or the required factory is not verified yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"hash","in":"query","required":true,"schema":{"$ref":"#/components/schemas/TransactionHash"}},{"name":"account","in":"query","required":true,"schema":{"$ref":"#/components/schemas/Address"},"description":"Connected paying wallet, or configured receiving wallet for merchant operations."},{"name":"recipient","in":"query","required":true,"schema":{"$ref":"#/components/schemas/Address"}},{"name":"amount","in":"query","required":false,"schema":{"$ref":"#/components/schemas/DecimalAmount"},"description":"Selected VNX amount to convert. Defaults to 10 when omitted; the same amount must be used for config, quote, prepare and receipt."}],"security":[{"AdminSession":[]}]}},"/api/admin/diagnostics":{"get":{"operationId":"getGatewayDiagnostics","tags":["Operations"],"summary":"Read scanner health and deployment readiness","responses":{"200":{"description":"Verified local API response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Diagnostics"}}}},"401":{"description":"Administrative sign-in is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid amount, address, policy or transaction request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Chain proof unavailable or the required factory is not verified yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"AdminSession":[]}]}},"/api/admin/integration":{"get":{"operationId":"getMerchantIntegration","tags":["Operations"],"summary":"Read integration setup without revealing credentials","responses":{"200":{"description":"Verified local API response.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Administrative sign-in is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid amount, address, policy or transaction request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Chain proof unavailable or the required factory is not verified yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"AdminSession":[]}]}},"/api/admin/integration/key":{"post":{"operationId":"revealLocalIntegrationKey","tags":["Operations"],"summary":"Explicitly reveal the private local integration credential","responses":{"200":{"description":"Verified local API response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"apiKey":{"type":"string"}},"required":["apiKey"]}}}},"401":{"description":"Administrative sign-in is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid amount, address, policy or transaction request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Chain proof unavailable or the required factory is not verified yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Origin","in":"header","required":true,"schema":{"type":"string","example":"https://dan-cash.com"},"description":"Must exactly match the configured HTTPS gateway origin."}],"description":"Local admin action. The credential is never included in public diagnostics or invoice responses. Keep it only in the integrating server; never customer-side JavaScript.","security":[{"AdminSession":[]}]}},"/api/merchant/invoices":{"get":{"operationId":"listMerchantInvoices","tags":["Merchant integration"],"summary":"List invoices with bounded pagination","responses":{"200":{"description":"Verified local API response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Invoice"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["items","total","limit","offset"]}}}},"422":{"description":"Invalid amount, address, policy or transaction request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Chain proof unavailable or the required factory is not verified yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"MerchantBearer":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}]},"post":{"operationId":"createMerchantInvoice","tags":["Merchant integration"],"summary":"Create or retry an order invoice from another server","responses":{"200":{"description":"Original invoice returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"201":{"description":"Invoice created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"400":{"description":"Missing idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflicting retry payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid invoice input.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Chain proof unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128},"description":"Retry the same canonical request with the same key to receive the original invoice. A changed request returns 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceInput"}}}},"security":[{"MerchantBearer":[]}],"description":"Bearer credential and Idempotency-Key are required. Origin is optional for server-to-server calls; a supplied browser Origin must still match the local server. Money values must be strings. Returns checkoutUrl and creationReplayed."}},"/api/merchant/invoices/{invoiceId}":{"get":{"operationId":"getMerchantInvoice","tags":["Merchant integration"],"summary":"Read authoritative invoice receipt and status","responses":{"200":{"description":"Verified local API response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"422":{"description":"Invalid amount, address, policy or transaction request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Chain proof unavailable or the required factory is not verified yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"MerchantBearer":[]}],"parameters":[{"name":"invoiceId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Opaque UUID returned when the invoice is created."}]}},"/api/merchant/events":{"get":{"operationId":"getMerchantEvents","tags":["Merchant integration"],"summary":"Read durable invoice events after an integration cursor","responses":{"200":{"description":"Verified local API response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventFeed"}}}},"422":{"description":"Invalid amount, address, policy or transaction request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Chain proof unavailable or the required factory is not verified yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"MerchantBearer":[]}],"parameters":[{"name":"after","in":"query","schema":{"type":"integer","minimum":0,"default":0}},{"name":"invoiceId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Opaque UUID returned when the invoice is created."}],"description":"Persist currentSequence after processing. resetRequired means the bounded history no longer covers the cursor; reconcile invoice snapshots before resuming. This pull feed is separate from signed webhook delivery."}},"/api/admin/session":{"get":{"operationId":"adminSession","tags":["Operations"],"summary":"Check administrative sign-in state","responses":{"200":{"description":"Session state without credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"authenticated":{"type":"boolean"},"localMode":{"type":"boolean"}}}}}}}},"post":{"operationId":"adminSignIn","tags":["Operations"],"summary":"Create a secure administrative session","parameters":[{"name":"Origin","in":"header","required":true,"schema":{"type":"string","example":"https://dan-cash.com"},"description":"Must exactly match this local server origin. The same-origin browser supplies this header automatically."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["password"],"properties":{"password":{"type":"string","format":"password"}}}}}},"responses":{"200":{"description":"Signed cookie session created.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Sign-in failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/admin/session/logout":{"post":{"operationId":"adminSignOut","tags":["Operations"],"summary":"Clear the administrative session cookie","parameters":[{"name":"Origin","in":"header","required":true,"schema":{"type":"string","example":"https://dan-cash.com"},"description":"Must exactly match this local server origin. The same-origin browser supplies this header automatically."}],"responses":{"200":{"description":"Cookie cleared.","content":{"application/json":{"schema":{"type":"object"}}}}}}}},"components":{"securitySchemes":{"MerchantBearer":{"type":"http","scheme":"bearer","description":"Private generated invoice API credential. Reveal explicitly in the local admin integration card; store in the integrating backend."},"AdminSession":{"type":"apiKey","in":"cookie","name":"__Host-vnx_admin","description":"Sign in at /login. HttpOnly Secure SameSite=Strict session; wallet signatures are separate."}},"schemas":{"InvoiceInput":{"type":"object","additionalProperties":false,"properties":{"amount":{"$ref":"#/components/schemas/DecimalAmount"},"orderReference":{"type":"string","maxLength":100},"description":{"type":"string","maxLength":240}},"required":["amount"]},"Diagnostics":{"type":"object","properties":{"factoryConfigured":{"type":"boolean"},"invoiceCount":{"type":"integer"},"storage":{"type":"string","enum":["local-ledger","private-blob-cas"]},"scanner":{"type":"object","properties":{"state":{"type":"string","enum":["waiting_for_factory","idle","scanning","healthy","degraded"]},"lastSuccessAt":{"type":["string","null"]},"lastErrorCode":{"type":["string","null"]},"failedInvoices":{"type":"integer"},"backlogInvoices":{"type":"integer"}}}}},"EventFeed":{"type":"object","additionalProperties":false,"properties":{"events":{"type":"array","items":{"type":"object","properties":{"sequence":{"type":"integer"},"invoiceId":{"type":"string","format":"uuid"},"type":{"type":"string"},"status":{"$ref":"#/components/schemas/InvoiceStatus"},"creditedAmount":{"$ref":"#/components/schemas/BaseUnits"},"fundedAmount":{"$ref":"#/components/schemas/BaseUnits"},"updatedAt":{"type":"string","format":"date-time"}}}},"currentSequence":{"type":"integer"},"oldestSequence":{"type":"integer"},"resetRequired":{"type":"boolean"}},"required":["events","currentSequence","oldestSequence","resetRequired"]},"Address":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$","description":"Nonzero EVM address; mixed-case addresses must have a valid checksum."},"TransactionHash":{"type":"string","pattern":"^0x[0-9a-fA-F]{64}$"},"BaseUnits":{"type":"string","pattern":"^(0|[1-9][0-9]*)$","description":"Integer amount in base units. Never a JSON number."},"DecimalAmount":{"type":"string","pattern":"^(?=.*[1-9])(?:0|[1-9][0-9]*)(?:\\.[0-9]{1,18})?$","description":"Positive VNX amount, at most 18 decimals and bounded by uint256 base units.","example":"10.25"},"InvoiceStatus":{"type":"string","enum":["PENDING","PARTIALLY_PAID","PAID","OVERPAID_REVIEW","EXPIRED"]},"PayoutAsset":{"type":"string","enum":["VNX","BNB"],"description":"Merchant payout asset on BNB Smart Chain. The customer pays VNX in both modes."},"SettlementMode":{"type":"string","enum":["DIRECT","VAULT"],"description":"DIRECT settles to the selected payout address. VAULT receives VNX into the immutable owner-bound merchant vault for later withdrawal."},"Error":{"type":"object","additionalProperties":false,"properties":{"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Settings":{"type":"object","additionalProperties":false,"properties":{"recipient":{"$ref":"#/components/schemas/Address"},"payoutAsset":{"$ref":"#/components/schemas/PayoutAsset"},"settlementMode":{"$ref":"#/components/schemas/SettlementMode"},"vaultOwner":{"anyOf":[{"$ref":"#/components/schemas/Address"},{"type":"null"}]},"vaultAddress":{"anyOf":[{"$ref":"#/components/schemas/Address"},{"type":"null"}]},"bnbRecipient":{"anyOf":[{"$ref":"#/components/schemas/Address"},{"type":"null"}]},"toleranceBps":{"type":"integer","enum":[0,1000]},"factoryAddress":{"anyOf":[{"$ref":"#/components/schemas/Address"},{"type":"null"}]}},"required":["recipient","payoutAsset","settlementMode","vaultOwner","vaultAddress","bnbRecipient","toleranceBps","factoryAddress"]},"SettingsInput":{"type":"object","additionalProperties":false,"properties":{"recipient":{"$ref":"#/components/schemas/Address"},"payoutAsset":{"$ref":"#/components/schemas/PayoutAsset"},"settlementMode":{"$ref":"#/components/schemas/SettlementMode"},"vaultOwner":{"anyOf":[{"$ref":"#/components/schemas/Address"},{"type":"null"}],"description":"Explicit wallet owner required in VAULT mode. Changes select a new vault for future invoices and do not transfer ownership of an existing vault."},"initializeVaultOwner":{"type":"boolean","description":"Optional first-time setup guard. True requires an explicit vaultOwner and settlementMode VAULT; the atomic settings write rejects 409 if any owner is already saved. Omit for intentional advanced settings changes. This flag is not persisted."},"bnbRecipient":{"anyOf":[{"$ref":"#/components/schemas/Address"},{"type":"null"}],"description":"Required nonzero BNB receiving address when payoutAsset is BNB. Null clears it only in VNX mode. Changes affect new invoices."},"toleranceBps":{"type":"integer","enum":[0,1000],"description":"0 = exact cumulative amount; 1000 = accepted cumulative amount from 90% through 110% inclusive."},"factoryAddress":{"anyOf":[{"$ref":"#/components/schemas/Address"},{"type":"null"}]}},"required":[]},"InvoiceConfig":{"type":"object","properties":{"chainId":{"type":"integer","const":56},"token":{"$ref":"#/components/schemas/Address"},"router":{"$ref":"#/components/schemas/Address"},"recipient":{"anyOf":[{"$ref":"#/components/schemas/Address"},{"type":"null"}]},"vnxRecipient":{"$ref":"#/components/schemas/Address"},"payoutAsset":{"$ref":"#/components/schemas/PayoutAsset"},"settlementMode":{"$ref":"#/components/schemas/SettlementMode"},"vaultOwner":{"anyOf":[{"$ref":"#/components/schemas/Address"},{"type":"null"}]},"vaultAddress":{"anyOf":[{"$ref":"#/components/schemas/Address"},{"type":"null"}]},"payoutRecipient":{"anyOf":[{"$ref":"#/components/schemas/Address"},{"type":"null"}]},"bnbRecipient":{"anyOf":[{"$ref":"#/components/schemas/Address"},{"type":"null"}]},"amountIn":{"$ref":"#/components/schemas/BaseUnits"},"paymentMode":{"type":"string","enum":["invoice","convert","receive"]},"invoiceKey":{"$ref":"#/components/schemas/TransactionHash"},"depositAddress":{"anyOf":[{"$ref":"#/components/schemas/Address"},{"type":"null"}]},"factoryAddress":{"anyOf":[{"$ref":"#/components/schemas/Address"},{"type":"null"}]},"paymentReady":{"type":"boolean"},"paySelector":{"type":["string","null"],"enum":["0x97d4df67","0x8afc4185",null],"description":"Verified factory method selector matching the immutable invoice payout asset."},"requireAccount":{"$ref":"#/components/schemas/Address"}}},"Invoice":{"type":"object","required":["id","amount","amountIn","recipient","payoutAsset","payoutRecipient","status","creditedAmount","paymentReady","config"],"properties":{"id":{"type":"string","format":"uuid"},"invoiceKey":{"$ref":"#/components/schemas/TransactionHash"},"amount":{"$ref":"#/components/schemas/DecimalAmount"},"orderReference":{"type":"string"},"description":{"type":"string"},"checkoutUrl":{"type":"string"},"creationReplayed":{"type":"boolean"},"amountIn":{"$ref":"#/components/schemas/BaseUnits"},"paymentAmountIn":{"$ref":"#/components/schemas/BaseUnits"},"paymentAmount":{"type":"string","description":"Remaining customer input; original expected amount remains immutable."},"recipient":{"$ref":"#/components/schemas/Address"},"payoutAsset":{"$ref":"#/components/schemas/PayoutAsset"},"settlementMode":{"$ref":"#/components/schemas/SettlementMode"},"vaultOwner":{"anyOf":[{"$ref":"#/components/schemas/Address"},{"type":"null"}]},"vaultAddress":{"anyOf":[{"$ref":"#/components/schemas/Address"},{"type":"null"}]},"payoutRecipient":{"anyOf":[{"$ref":"#/components/schemas/Address"},{"type":"null"}]},"bnbRecipient":{"anyOf":[{"$ref":"#/components/schemas/Address"},{"type":"null"}]},"toleranceBps":{"type":"integer","enum":[0,1000]},"status":{"$ref":"#/components/schemas/InvoiceStatus"},"creditedAmount":{"$ref":"#/components/schemas/BaseUnits"},"creditedVnx":{"type":"string"},"creditedBnbAmount":{"$ref":"#/components/schemas/BaseUnits","description":"Verified cumulative native BNB output in wei. Separately recorded from VNX invoice fulfillment credits."},"creditedBnb":{"type":"string","description":"Formatted cumulative BNB received; zero for VNX invoices."},"fundedAmount":{"$ref":"#/components/schemas/BaseUnits"},"fundedStatus":{"type":"string","enum":["NONE","AWAITING_FORWARD"]},"paymentReady":{"type":"boolean"},"readinessReason":{"type":["string","null"]},"depositAddress":{"anyOf":[{"$ref":"#/components/schemas/Address"},{"type":"null"}]},"factoryAddress":{"anyOf":[{"$ref":"#/components/schemas/Address"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"createdBlock":{"$ref":"#/components/schemas/BaseUnits"},"reviewState":{"type":"string","enum":["OVERPAID_REVIEW"]},"excessAmount":{"$ref":"#/components/schemas/BaseUnits"},"transfers":{"type":"array","items":{"type":"object"}},"config":{"$ref":"#/components/schemas/InvoiceConfig"}}},"Quote":{"type":"object","properties":{"amountIn":{"$ref":"#/components/schemas/BaseUnits"},"expectedVnxNet":{"$ref":"#/components/schemas/BaseUnits"},"expectedOut":{"$ref":"#/components/schemas/BaseUnits"},"minOut":{"$ref":"#/components/schemas/BaseUnits"},"payoutAsset":{"$ref":"#/components/schemas/PayoutAsset"},"expectedBnb":{"type":"string"},"minimumBnb":{"type":"string"},"quotedAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"taxBps":{"$ref":"#/components/schemas/BaseUnits"},"account":{"type":["object","null"]},"depositAddress":{"$ref":"#/components/schemas/Address"},"factoryAddress":{"$ref":"#/components/schemas/Address"}}},"UnsignedTransaction":{"type":"object","additionalProperties":false,"properties":{"from":{"$ref":"#/components/schemas/Address"},"to":{"$ref":"#/components/schemas/Address"},"data":{"type":"string","pattern":"^0x[0-9a-fA-F]+$"},"value":{"type":"string","const":"0x0"},"gas":{"type":"string","pattern":"^0x[0-9a-fA-F]+$"},"gasPrice":{"type":"string","pattern":"^0x[0-9a-fA-F]+$"},"chainId":{"type":"string","const":"0x38"}},"required":["from","data","value","gas","gasPrice","chainId"]},"PreparedTransaction":{"type":"object","required":["transaction"],"properties":{"action":{"type":"string","enum":["approve","pay","swap","forward","withdrawVnx","withdrawBnb"]},"transaction":{"$ref":"#/components/schemas/UnsignedTransaction"},"quote":{"$ref":"#/components/schemas/Quote"},"estimatedFeeBnb":{"type":"string"}}},"Receipt":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["pending","confirming","success","reverted"]},"action":{"type":"string"},"account":{"$ref":"#/components/schemas/Address"},"recipient":{"$ref":"#/components/schemas/Address"},"invoiceKey":{"$ref":"#/components/schemas/TransactionHash"},"depositAddress":{"$ref":"#/components/schemas/Address"},"amountReceived":{"$ref":"#/components/schemas/BaseUnits"},"amountPaid":{"$ref":"#/components/schemas/BaseUnits"},"payoutAsset":{"$ref":"#/components/schemas/PayoutAsset"},"receivedBnb":{"type":"string"},"amountOut":{"$ref":"#/components/schemas/BaseUnits"},"factoryAddress":{"$ref":"#/components/schemas/Address"},"runtimeCodeHash":{"$ref":"#/components/schemas/TransactionHash"},"invoiceStatus":{"$ref":"#/components/schemas/InvoiceStatus"},"creditedAmount":{"$ref":"#/components/schemas/BaseUnits"}}},"VaultReference":{"type":"object","additionalProperties":false,"properties":{"factoryAddress":{"$ref":"#/components/schemas/Address"},"owner":{"$ref":"#/components/schemas/Address"},"vaultAddress":{"$ref":"#/components/schemas/Address"},"createdAt":{"type":"string","format":"date-time"}},"required":["factoryAddress","owner","vaultAddress","createdAt"]},"VaultWithdrawal":{"type":"object","additionalProperties":false,"properties":{"hash":{"$ref":"#/components/schemas/TransactionHash"},"logIndex":{"type":"integer","minimum":0},"factoryAddress":{"$ref":"#/components/schemas/Address"},"owner":{"$ref":"#/components/schemas/Address"},"vaultAddress":{"$ref":"#/components/schemas/Address"},"recipient":{"$ref":"#/components/schemas/Address"},"action":{"type":"string","enum":["withdrawVnx","withdrawBnb"]},"asset":{"type":"string","enum":["VNX","BNB"]},"amountIn":{"$ref":"#/components/schemas/BaseUnits"},"amountDebited":{"$ref":"#/components/schemas/BaseUnits"},"amountReceived":{"$ref":"#/components/schemas/BaseUnits"},"blockNumber":{"$ref":"#/components/schemas/BaseUnits"},"blockHash":{"$ref":"#/components/schemas/TransactionHash"},"recordedAt":{"type":"string","format":"date-time"}},"required":["hash","logIndex","factoryAddress","owner","vaultAddress","recipient","action","asset","amountIn","amountDebited","amountReceived","blockNumber","blockHash","recordedAt"]},"VaultOverview":{"allOf":[{"$ref":"#/components/schemas/Quote"},{"type":"object","required":["ready","config","vaults","withdrawals"],"properties":{"ready":{"type":"boolean"},"reason":{"type":"string"},"deployed":{"type":"boolean"},"vaultOwner":{"$ref":"#/components/schemas/Address"},"vaultAddress":{"$ref":"#/components/schemas/Address"},"balanceBaseUnits":{"$ref":"#/components/schemas/BaseUnits"},"balanceVnx":{"type":"string"},"factoryAddress":{"$ref":"#/components/schemas/Address"},"ownerBnbBalanceBaseUnits":{"$ref":"#/components/schemas/BaseUnits"},"config":{"type":"object","properties":{"paymentMode":{"type":"string","const":"vault"},"chainId":{"type":"integer","const":56},"owner":{"anyOf":[{"$ref":"#/components/schemas/Address"},{"type":"null"}]},"vaultOwner":{"anyOf":[{"$ref":"#/components/schemas/Address"},{"type":"null"}]},"vaultAddress":{"anyOf":[{"$ref":"#/components/schemas/Address"},{"type":"null"}]},"factoryAddress":{"anyOf":[{"$ref":"#/components/schemas/Address"},{"type":"null"}]},"factoryRuntimeCodeHash":{"$ref":"#/components/schemas/TransactionHash"},"selectors":{"type":"object","properties":{"withdrawVnx":{"type":"string","pattern":"^0x[0-9a-fA-F]{8}$"},"withdrawBnb":{"type":"string","pattern":"^0x[0-9a-fA-F]{8}$"}}}}},"vaults":{"type":"array","items":{"$ref":"#/components/schemas/VaultReference"}},"withdrawals":{"type":"array","items":{"$ref":"#/components/schemas/VaultWithdrawal"}}}}]},"VaultWithdrawalReceipt":{"allOf":[{"$ref":"#/components/schemas/Receipt"},{"type":"object","properties":{"verified":{"type":"boolean"},"finalized":{"type":"boolean"},"owner":{"$ref":"#/components/schemas/Address"},"vaultAddress":{"$ref":"#/components/schemas/Address"},"asset":{"type":"string","enum":["VNX","BNB"]},"amountIn":{"$ref":"#/components/schemas/BaseUnits"},"amountDebited":{"$ref":"#/components/schemas/BaseUnits"},"historyRecorded":{"type":"boolean"},"withdrawals":{"type":"array","items":{"$ref":"#/components/schemas/VaultWithdrawal"}}}}]},"FactoryArtifact":{"type":"object","required":["contractName","abi","bytecode","deployedBytecode","runtimeCodeHash"],"properties":{"contractName":{"type":"string"},"compilerVersion":{"type":"string"},"sourcePath":{"type":"string"},"abi":{"type":"array","items":{"type":"object"}},"bytecode":{"type":"string"},"deployedBytecode":{"type":"string"},"runtimeCodeHash":{"$ref":"#/components/schemas/TransactionHash"}}}}}}