{
  "openapi": "3.1.0",
  "info": {
    "title": "Nanswap Pay API",
    "version": "1.0.0",
    "description": "Accept crypto payments (Nano/XNO with 0 fees, plus BTC, XMR, ETH, USDT and 1,000+ other coins) and receive payouts in XNO, NANUSD or USDT-MATIC.\n\nMerchant flow: (1) optionally GET /fiat-currencies and /payin-currencies, (2) POST /order with your secret key, (3) redirect the customer to the returned paymentLink (hosted checkout) or show payinAddress + expectedAmountFrom yourself, (4) receive a webhook on callbackUrl (verify the x-nanswap-sig header) or poll GET /order?id=... until status is completed.\n\nIf payinCurrency is omitted on POST /order, a draft invoice (status pending-currency) is created and the customer picks a coin on the hosted checkout page.\n\nIMPORTANT: errors are returned with HTTP 200 and a JSON body {\"error\": \"message\"}. Always check for an error field. The only non-200 error is 429 when a rate limit is hit.\n\nGet API keys at https://nanswap.com/account?tab=nanswap-pay. Human-readable docs: https://nanswap.com/pay/api",
    "contact": {
      "name": "Nanswap",
      "email": "contact@nanswap.com",
      "url": "https://nanswap.com/pay"
    }
  },
  "servers": [
    {
      "url": "https://api.nanswap.com/pay"
    }
  ],
  "externalDocs": {
    "description": "Nanswap Pay REST API documentation",
    "url": "https://nanswap.com/pay/api"
  },
  "tags": [
    { "name": "Orders", "description": "Create and track payment invoices." },
    { "name": "Currencies", "description": "Supported price and payment currencies." },
    { "name": "Checkout", "description": "Endpoints used by the hosted checkout page on behalf of the payer. Useful for an agent paying a Nanswap Pay invoice." }
  ],
  "components": {
    "securitySchemes": {
      "secretKey": {
        "type": "apiKey",
        "in": "header",
        "name": "x-nanswap-pay-key",
        "description": "Secret API key from the Nanswap Pay dashboard. Server-side only, never expose it in a browser."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": { "type": "string", "example": "Invalid API key" }
        }
      },
      "OrderStatus": {
        "type": "string",
        "description": "pending-currency: waiting for the customer to choose a coin. waiting: waiting for the customer payment. confirming: deposit detected, waiting for confirmations. exchanging / sending / processing: payment received, payout in progress. completed: payout sent, the order is paid. expired: rate expired before payment (can be refreshed). underpaid: customer sent less than expected. error / processing-error / failed / refunded: contact support.",
        "enum": [
          "pending-currency",
          "waiting",
          "confirming",
          "exchanging",
          "sending",
          "processing",
          "completed",
          "expired",
          "underpaid",
          "error",
          "processing-error",
          "failed",
          "refunded"
        ]
      },
      "PayoutCurrency": {
        "type": "string",
        "enum": ["XNO", "NANUSD", "USDT-MATIC"],
        "description": "Currency the merchant receives."
      },
      "CreateOrderRequest": {
        "type": "object",
        "required": ["priceAmount"],
        "properties": {
          "priceAmount": { "type": "number", "description": "Amount to charge, in priceCurrency.", "example": 10 },
          "priceCurrency": { "type": "string", "description": "Currency of the price, from GET /fiat-currencies (USD, EUR, XNO...). Defaults to the payout currency.", "example": "USD" },
          "payinCurrency": { "type": "string", "description": "Ticker the customer pays with, from GET /payin-currencies (XNO, BTC, XMR, ETH...). Omit to create a draft invoice and let the customer choose on the hosted checkout.", "example": "XNO" },
          "invoiceId": { "type": "string", "maxLength": 128, "description": "Your own order ID. Returned as invoiceIdPartner and in webhooks as invoicePartnerId.", "example": "order_123" },
          "callbackUrl": { "type": "string", "format": "uri", "description": "Webhook URL called on every status change. Must be http(s), not an IP address and not a nanswap.com host.", "example": "https://example.com/webhooks/nanswap" },
          "successUrl": { "type": "string", "format": "uri", "description": "Where the customer is sent after a successful payment.", "example": "https://example.com/thank-you" },
          "cancelUrl": { "type": "string", "format": "uri", "description": "Where the customer is sent if they cancel.", "example": "https://example.com/cart" },
          "payoutAddress": { "type": "string", "description": "Payout address override. Only used when the payout method is set to dynamic in the dashboard." },
          "payoutCurrency": { "$ref": "#/components/schemas/PayoutCurrency" },
          "publicKey": { "type": "string", "description": "Public key, used instead of the secret key header by browser integrations (widget, payment link). Server integrations should use the x-nanswap-pay-key header." }
        }
      },
      "CreateOrderResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "invoiceId": { "type": "string", "description": "Nanswap invoice ID. Use it with GET /order.", "example": "0b8d7f59-e4f0-4c9e-951f-49b644115adb" },
          "invoiceIdPartner": { "type": ["string", "null"], "description": "Your invoiceId, if sent." },
          "status": { "$ref": "#/components/schemas/OrderStatus" },
          "paymentLink": { "type": "string", "format": "uri", "description": "Hosted checkout URL to send the customer to.", "example": "https://nanswap.com/pay/0b8d7f59-e4f0-4c9e-951f-49b644115adb" },
          "transactionId": { "type": "string", "description": "Only when payinCurrency was set." },
          "payinCurrency": { "type": "string", "description": "Only when payinCurrency was set.", "example": "XNO" },
          "paymentCurrency": { "$ref": "#/components/schemas/PayoutCurrency" },
          "payinAddress": { "type": "string", "description": "Deposit address the customer must pay to. Only when payinCurrency was set.", "example": "nano_3udf3w3xf5rgperkpqwosedx13h3hbdzlt69utea8wds4mwqaoy6917hs15x" },
          "expectedAmountFrom": { "type": "number", "description": "Exact amount of payinCurrency to send. Only when payinCurrency was set.", "example": 30.303 },
          "expectedPayoutAmount": { "type": "string", "description": "Amount the merchant receives, in paymentCurrency.", "example": "10.000" },
          "expireAt": { "type": "string", "format": "date-time", "description": "The rate is valid until this date." }
        }
      },
      "Order": {
        "type": "object",
        "properties": {
          "status": { "$ref": "#/components/schemas/OrderStatus" },
          "invoiceId": { "type": "string" },
          "invoiceIdPartner": { "type": ["string", "null"] },
          "payinCurrency": { "type": ["string", "null"], "description": "Absent while status is pending-currency." },
          "paymentCurrency": { "$ref": "#/components/schemas/PayoutCurrency" },
          "payinAddress": { "type": ["string", "null"], "description": "Deposit address. Absent while status is pending-currency." },
          "payinExtraId": { "type": ["string", "null"], "description": "Memo / destination tag the customer must include, for coins that need one." },
          "expectedAmountFrom": { "type": ["number", "null"], "description": "Exact amount of payinCurrency to send." },
          "expectedPayoutAmount": { "type": ["string", "number", "null"] },
          "priceAmount": { "type": ["number", "null"] },
          "priceCurrency": { "type": ["string", "null"] },
          "expireAt": { "type": "string", "format": "date-time" },
          "depositDetectedAt": { "type": ["string", "null"], "format": "date-time" },
          "completedAt": { "type": ["string", "null"], "format": "date-time" },
          "shopName": { "type": ["string", "null"] },
          "publicKey": { "type": ["string", "null"], "description": "Merchant public key. Only while status is pending-currency, for use with GET /order-estimate." },
          "successUrl": { "type": ["string", "null"] },
          "cancelUrl": { "type": ["string", "null"] }
        }
      },
      "Estimate": {
        "type": "object",
        "properties": {
          "expectedAmountFrom": { "type": "number", "description": "Amount of payinCurrency the customer would pay.", "example": 30.303 },
          "payoutAmount": { "type": "number", "example": 10 },
          "payoutCurrency": { "$ref": "#/components/schemas/PayoutCurrency" },
          "warningHighFees": { "type": "boolean", "description": "True when network fees are a large share of the amount (small payments in coins with high fees)." }
        }
      },
      "InvoiceListItem": {
        "type": "object",
        "properties": {
          "invoiceId": { "type": "string" },
          "invoicePartnerId": { "type": ["string", "null"] },
          "status": { "$ref": "#/components/schemas/OrderStatus" },
          "payinCurrency": { "type": ["string", "null"] },
          "payoutCurrency": { "$ref": "#/components/schemas/PayoutCurrency" },
          "payoutMethod": { "type": "string", "enum": ["internal", "address", "dynamic"] },
          "payoutAddress": { "type": ["string", "null"] },
          "expectedAmountFrom": { "type": ["number", "null"] },
          "expectedPayoutAmount": { "type": ["string", "number", "null"] },
          "payoutAmount": { "type": ["number", "null"] },
          "payoutHash": { "type": ["string", "null"] },
          "createdAt": { "type": "string", "format": "date-time" }
        }
      },
      "WebhookPayload": {
        "type": "object",
        "description": "POSTed to callbackUrl on every status change. The x-nanswap-sig header is the hex HMAC-SHA512 of JSON.stringify(payload, Object.keys(payload).sort()) using your webhook secret. Verify it, check priceAmount/priceCurrency match your order, and make your handler idempotent (the same webhook can arrive more than once). Treat the order as paid only when status is completed.",
        "properties": {
          "invoicePartnerId": { "type": ["string", "null"] },
          "invoiceId": { "type": "string" },
          "status": { "$ref": "#/components/schemas/OrderStatus" },
          "expectedAmountFrom": { "type": "number" },
          "amountFrom": { "type": "number" },
          "payoutAmount": { "type": "number" },
          "payoutCurrency": { "$ref": "#/components/schemas/PayoutCurrency" },
          "payinCurrency": { "type": "string" },
          "priceCurrency": { "type": "string" },
          "priceAmount": { "type": "number" },
          "payoutMethod": { "type": "string", "enum": ["internal", "address", "dynamic"] },
          "payoutHash": { "type": ["string", "null"] },
          "payoutAddress": { "type": ["string", "null"] }
        }
      }
    }
  },
  "paths": {
    "/order": {
      "post": {
        "operationId": "createOrder",
        "tags": ["Orders"],
        "summary": "Create a payment invoice",
        "description": "Creates an invoice. With payinCurrency, returns a deposit address and exact amount right away (status waiting). Without it, returns a draft (status pending-currency) whose paymentLink lets the customer choose a coin. Rate limited to 500 orders per IP per 24h.",
        "security": [{ "secretKey": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CreateOrderRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The created invoice, or {error}.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    { "$ref": "#/components/schemas/CreateOrderResponse" },
                    { "$ref": "#/components/schemas/Error" }
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Daily order creation limit reached.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          }
        }
      },
      "get": {
        "operationId": "getOrder",
        "tags": ["Orders"],
        "summary": "Get an invoice and its status",
        "description": "No authentication. Poll every few seconds to follow a payment; stop when status is completed or a final error status.",
        "security": [],
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "required": true,
            "description": "invoiceId returned by POST /order.",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "The invoice, or {error} (e.g. Order not found).",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    { "$ref": "#/components/schemas/Order" },
                    { "$ref": "#/components/schemas/Error" }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/order-estimate": {
      "get": {
        "operationId": "getOrderEstimate",
        "tags": ["Orders"],
        "summary": "Estimate how much the customer will pay",
        "description": "Price preview before creating an invoice. Authenticate with the secret key header or pass publicKey; without either, the payout currency defaults to XNO unless payoutCurrency is set.",
        "security": [{ "secretKey": [] }, {}],
        "parameters": [
          { "name": "payinCurrency", "in": "query", "required": true, "description": "Coin the customer pays with.", "schema": { "type": "string", "example": "XNO" } },
          { "name": "priceAmount", "in": "query", "required": true, "schema": { "type": "number", "example": 10 } },
          { "name": "priceCurrency", "in": "query", "required": false, "description": "Defaults to the payout currency.", "schema": { "type": "string", "example": "USD" } },
          { "name": "payoutCurrency", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/PayoutCurrency" } },
          { "name": "publicKey", "in": "query", "required": false, "description": "Merchant public key, instead of the secret key header.", "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "The estimate, or {error}.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    { "$ref": "#/components/schemas/Estimate" },
                    { "$ref": "#/components/schemas/Error" }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/invoices": {
      "get": {
        "operationId": "listInvoices",
        "tags": ["Orders"],
        "summary": "List your invoices",
        "description": "Most recent first, 20 per page.",
        "security": [{ "secretKey": [] }],
        "parameters": [
          { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }
        ],
        "responses": {
          "200": {
            "description": "A page of invoices, or {error}.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "type": "object",
                      "properties": {
                        "invoices": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceListItem" } },
                        "total": { "type": "integer" },
                        "page": { "type": "integer" },
                        "pages": { "type": "integer" }
                      }
                    },
                    { "$ref": "#/components/schemas/Error" }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/payin-currencies": {
      "get": {
        "operationId": "listPayinCurrencies",
        "tags": ["Currencies"],
        "summary": "Coins customers can pay with",
        "description": "Map of ticker to currency info. Keys are valid payinCurrency values. No authentication.",
        "security": [],
        "responses": {
          "200": {
            "description": "Currencies keyed by ticker.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": {
                    "type": "object",
                    "properties": {
                      "name": { "type": "string", "example": "Nano" },
                      "ticker": { "type": "string", "example": "XNO" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/fiat-currencies": {
      "get": {
        "operationId": "listPriceCurrencies",
        "tags": ["Currencies"],
        "summary": "Currencies a price can be set in",
        "description": "Valid priceCurrency values: fiat codes (USD, EUR, GBP...) plus XNO. No authentication.",
        "security": [],
        "responses": {
          "200": {
            "description": "List of currency codes.",
            "content": {
              "application/json": {
                "schema": { "type": "array", "items": { "type": "string" }, "example": ["USD", "EUR", "GBP", "XNO"] }
              }
            }
          }
        }
      }
    },
    "/order/select-currency": {
      "post": {
        "operationId": "selectOrderCurrency",
        "tags": ["Checkout"],
        "summary": "Choose the coin to pay a draft invoice with",
        "description": "For an invoice in status pending-currency. Assigns a deposit address and amount; then GET /order returns payinAddress and expectedAmountFrom. No authentication.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["invoiceId", "payinCurrency"],
                "properties": {
                  "invoiceId": { "type": "string" },
                  "payinCurrency": { "type": "string", "example": "XNO" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated invoice fields, or {error}.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    { "$ref": "#/components/schemas/Order" },
                    { "$ref": "#/components/schemas/Error" }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/order/refresh": {
      "post": {
        "operationId": "refreshOrderRate",
        "tags": ["Checkout"],
        "summary": "Get a new rate for an expired invoice",
        "description": "For an invoice in status waiting or expired. Do not use it if funds were already sent for the old rate. No authentication.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["invoiceId"],
                "properties": { "invoiceId": { "type": "string" } }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated invoice fields, or {error}.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    { "$ref": "#/components/schemas/Order" },
                    { "$ref": "#/components/schemas/Error" }
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "webhooks": {
    "orderStatusChanged": {
      "post": {
        "summary": "Invoice status changed",
        "description": "Sent to the callbackUrl of the order.",
        "parameters": [
          {
            "name": "x-nanswap-sig",
            "in": "header",
            "required": true,
            "description": "Hex HMAC-SHA512 of the payload (keys sorted alphabetically) with your webhook secret.",
            "schema": { "type": "string" }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/WebhookPayload" }
            }
          }
        },
        "responses": {
          "200": { "description": "Return any 2xx to acknowledge." }
        }
      }
    }
  }
}
