{"openapi": "3.1.0", "info": {"title": "Xazum API", "version": "1.0.0", "description": "Accept USDT-TRC20. Create an invoice, show the payer the address, and act on the signed webhook we send when the money is confirmed.\n\nAuthenticate with `X-Api-Key`. Every response is JSON. Amounts are decimal strings, never floats \u2014 parse them as decimals."}, "paths": {"/api/v1/addresses": {"post": {"operationId": "api_v1_get_address", "summary": "Get a payer's permanent address", "parameters": [], "responses": {"201": {"description": "Created", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AddressOut"}}}}, "200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AddressOut"}}}}}, "description": "Return the deposit address for one of your users, creating it once.\n\nThis is the cheap path and the one to prefer for balance top-ups. The payer\nkeeps the same address forever, so their payments accumulate and one sweep\nmoves all of them \u2014 roughly a sixth of the on-chain cost of a fresh address\nper payment. It also keeps every repeat payment on the cheaper transfer\n(a transfer into a non-empty address costs half the energy), which is money\npaid by your user, not by you.\n\nIdempotent by construction: the same `customer_ref` always returns the same\naddress, so it is safe to call on every page load.", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/AddressIn"}}}, "required": true}, "security": [{"ApiKeyAuth": []}]}}, "/api/v1/invoices": {"post": {"operationId": "api_v1_create_invoice", "summary": "Create an invoice", "parameters": [], "responses": {"201": {"description": "Created", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/InvoiceOut"}}}}, "200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/InvoiceOut"}}}}}, "description": "Issue a fresh deposit address for an amount.\n\nIdempotent on `order_id`: retrying a create returns the original invoice\nwith 200 rather than minting a second address. That matters \u2014 a duplicate\naddress for one order means one payment the merchant may never reconcile.", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/InvoiceIn"}}}, "required": true}, "security": [{"ApiKeyAuth": []}]}}, "/api/v1/invoices/{invoice_id}": {"get": {"operationId": "api_v1_get_invoice", "summary": "Read an invoice", "parameters": [{"in": "path", "name": "invoice_id", "schema": {"format": "uuid", "title": "Invoice Id", "type": "string"}, "required": true}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/InvoiceOut"}}}}}, "description": "Authoritative state. Poll this whenever a webhook has not arrived.", "security": [{"ApiKeyAuth": []}]}}, "/api/v1/invoices/by-order/{order_id}": {"get": {"operationId": "api_v1_get_invoice_by_order", "summary": "Read an invoice by your own id", "parameters": [{"in": "path", "name": "order_id", "schema": {"title": "Order Id", "type": "string"}, "required": true}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/InvoiceOut"}}}}}, "security": [{"ApiKeyAuth": []}]}}, "/api/v1/deposits": {"get": {"operationId": "api_v1_list_deposits", "summary": "List deposits", "parameters": [{"in": "query", "name": "invoice_id", "schema": {"anyOf": [{"format": "uuid", "type": "string"}, {"type": "null"}], "title": "Invoice Id"}, "required": false}, {"in": "query", "name": "status", "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Status"}, "required": false}, {"in": "query", "name": "limit", "schema": {"default": 100, "minimum": 1, "title": "Limit", "type": "integer"}, "required": false}, {"in": "query", "name": "offset", "schema": {"default": 0, "minimum": 0, "title": "Offset", "type": "integer"}, "required": false}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/PagedDepositOut"}}}}}, "description": "Every transfer we have seen for this merchant, newest first.", "security": [{"ApiKeyAuth": []}]}}, "/api/v1/health": {"get": {"operationId": "api_v1_health", "summary": "Service health", "parameters": [], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/HealthOut"}}}}}, "description": "Scanner lag is the number that matters.\n\nA growing lag means deposits are arriving on chain and we are not seeing\nthem yet \u2014 payments look missing to your users while nothing is technically\n\"down\". Alert on this, not on whether the API answers.", "security": [{"ApiKeyAuth": []}]}}}, "components": {"schemas": {"AddressOut": {"properties": {"address": {"title": "Address", "type": "string"}, "network": {"title": "Network", "type": "string"}, "currency": {"title": "Currency", "type": "string"}, "customer_ref": {"title": "Customer Ref", "type": "string"}, "created_at": {"title": "Created At", "type": "string"}}, "required": ["address", "network", "currency", "customer_ref", "created_at"], "title": "AddressOut", "type": "object"}, "AddressIn": {"properties": {"customer_ref": {"description": "Your identifier for this payer \u2014 a user id, not an email. The same value always returns the same address.", "maxLength": 120, "title": "Customer Ref", "type": "string"}}, "required": ["customer_ref"], "title": "AddressIn", "type": "object"}, "InvoiceOut": {"properties": {"id": {"format": "uuid", "title": "Id", "type": "string"}, "order_id": {"title": "Order Id", "type": "string"}, "status": {"title": "Status", "type": "string"}, "address": {"title": "Address", "type": "string"}, "network": {"title": "Network", "type": "string"}, "currency": {"title": "Currency", "type": "string"}, "payment_url": {"title": "Payment Url", "type": "string"}, "amount_requested": {"anyOf": [{"type": "number"}, {"pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "type": "string"}], "title": "Amount Requested"}, "amount_received": {"anyOf": [{"type": "number"}, {"pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "type": "string"}], "title": "Amount Received"}, "outstanding": {"anyOf": [{"type": "number"}, {"pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "type": "string"}], "title": "Outstanding"}, "expires_at": {"title": "Expires At", "type": "string"}, "created_at": {"title": "Created At", "type": "string"}, "paid_at": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Paid At"}, "return_url": {"title": "Return Url", "type": "string"}, "metadata": {"additionalProperties": true, "title": "Metadata", "type": "object"}}, "required": ["id", "order_id", "status", "address", "network", "currency", "payment_url", "amount_requested", "amount_received", "outstanding", "expires_at", "created_at", "paid_at", "return_url", "metadata"], "title": "InvoiceOut", "type": "object"}, "InvoiceIn": {"properties": {"order_id": {"description": "Your identifier for this payment. Reusing one returns the existing invoice instead of creating a second address.", "maxLength": 120, "title": "Order Id", "type": "string"}, "amount": {"anyOf": [{"exclusiveMinimum": 0.0, "type": "number"}, {"pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "type": "string"}], "description": "Amount in USDT, e.g. \"25.00\".", "title": "Amount"}, "currency": {"default": "USDT", "description": "Only USDT is supported today.", "title": "Currency", "type": "string"}, "ttl": {"anyOf": [{"maximum": 86400, "minimum": 300, "type": "integer"}, {"type": "null"}], "description": "Seconds before the address stops being advertised. Late payments are still credited.", "title": "Ttl"}, "return_url": {"default": "", "description": "Where to send the payer when the checkout finishes. A button appears on the payment page, and a paid invoice redirects there automatically after a few seconds. http/https only.", "maxLength": 500, "title": "Return Url", "type": "string"}, "metadata": {"additionalProperties": true, "description": "Echoed back on every webhook. Max 4 KB.", "title": "Metadata", "type": "object"}}, "required": ["order_id", "amount"], "title": "InvoiceIn", "type": "object"}, "Input": {"properties": {"limit": {"default": 100, "minimum": 1, "title": "Limit", "type": "integer"}, "offset": {"default": 0, "minimum": 0, "title": "Offset", "type": "integer"}}, "title": "Input", "type": "object"}, "DepositOut": {"properties": {"id": {"format": "uuid", "title": "Id", "type": "string"}, "invoice_id": {"anyOf": [{"format": "uuid", "type": "string"}, {"type": "null"}], "title": "Invoice Id"}, "txid": {"title": "Txid", "type": "string"}, "amount": {"anyOf": [{"type": "number"}, {"pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "type": "string"}], "title": "Amount"}, "confirmations": {"title": "Confirmations", "type": "integer"}, "status": {"title": "Status", "type": "string"}, "from_address": {"title": "From Address", "type": "string"}, "block_number": {"title": "Block Number", "type": "integer"}, "seen_at": {"title": "Seen At", "type": "string"}}, "required": ["id", "invoice_id", "txid", "amount", "confirmations", "status", "from_address", "block_number", "seen_at"], "title": "DepositOut", "type": "object"}, "PagedDepositOut": {"properties": {"items": {"items": {"$ref": "#/components/schemas/DepositOut"}, "title": "Items", "type": "array"}, "count": {"title": "Count", "type": "integer"}}, "required": ["items", "count"], "title": "PagedDepositOut", "type": "object"}, "HealthOut": {"properties": {"ok": {"title": "Ok", "type": "boolean"}, "scanner_lag_blocks": {"title": "Scanner Lag Blocks", "type": "integer"}}, "required": ["ok", "scanner_lag_blocks"], "title": "HealthOut", "type": "object"}}, "securitySchemes": {"ApiKeyAuth": {"type": "apiKey", "in": "header", "name": "X-Api-Key"}}}, "servers": []}