openapi: "3.1.0"
info:
  title: "CryptoPayr API"
  version: "1.0.0"
  summary: "Accept crypto payments, pay out, transfer, refund, pull market data, and run keyless crypto swaps."
  description: "REST API for CryptoPayr. JSON in, JSON out.\n\n**Auth** — send your secret key as a Bearer token: `Authorization: Bearer sk_live_…`. Money-out endpoints (payout/transfer create) require a separate withdrawal key `wk_live_…`. Market-data and exchange endpoints are public.\n\n**Envelopes** — success: `{status:\"success\", message, data, timestamp}`; error: `{status:\"failed\", error, timestamp}` with a matching HTTP status.\n\n**Pagination** — list endpoints take `page` (50 per page) and return `{page, per_page, total, total_pages, has_more, data:[…]}`.\n\n**Idempotency** — send an `Idempotency-Key` header on create calls; replays within 24h return the original result."
  contact:
    name: "CryptoPayr support"
    email: "support@cryptopayr.com"
servers:
  -
    url: "https://cryptopayr.com/api/v1"
    description: "Production"
tags:
  -
    name: "Payments"
    description: "Create, look up, cancel and reconcile payments."
  -
    name: "Payment links"
    description: "Reusable hosted payment links."
  -
    name: "Account"
    description: "Balance and account details."
  -
    name: "Refunds"
    description: "Issue and list refunds."
  -
    name: "Market data"
    description: "Public live rates and conversion."
  -
    name: "Payouts"
    description: "Withdraw your balance on-chain."
  -
    name: "Transfers"
    description: "Instant off-chain transfers between accounts."
  -
    name: "Exchange"
    description: "Public, keyless crypto-to-crypto swaps."
paths:
  /payment/create:
    post:
      tags:
        - "Payments"
      summary: "Create a payment"
      responses:
        "200":
          description: "data: tid, status=\"CREATED\", amount, currency, checkout_url. Platform calls echo on_behalf_of, platform_fee_percent, platform_fee_fixed."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Success"
        default:
          description: "Error — see the `error` message and HTTP status."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        -
          ApiKey: []
      parameters:
        -
          name: "Idempotency-Key"
          in: "header"
          required: false
          schema:
            type: "string"
          description: "Optional client key; a replay within 24h returns the original result with `Idempotency-Replayed: true`."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: "object"
              properties:
                amount:
                  type: "number"
                  description: "Order amount in the pricing currency."
                  example: 49
                currency:
                  type: "string"
                  description: "Three-letter fiat pricing currency."
                  example: "USD"
                webhook_url:
                  type: "string"
                  description: "Override your default signed webhook URL."
                success_url:
                  type: "string"
                  description: "Redirect the buyer here after payment."
                cancel_url:
                  type: "string"
                  description: "Redirect the buyer here if they cancel."
                pay_currency:
                  type: "string"
                  description: "Pin the pay-in coin (skips the picker), e.g. BTC."
                pay_network:
                  type: "string"
                  description: "Pin the pay-in network, e.g. TRON."
                buyer_pays_fees:
                  type: "integer"
                  description: "1 = add the processing fee on top of the amount."
                metadata:
                  type: "string"
                  description: "Free-form reference stored on the payment (≤255)."
                on_behalf_of:
                  type: "string"
                  description: "Platform accounts only: client account id (usr_…)."
                platform_fee_percent:
                  type: "number"
                  description: "Platform accounts only: commission percent (0–50)."
                platform_fee_fixed:
                  type: "number"
                  description: "Platform accounts only: fixed commission."
              required:
                - "amount"
                - "currency"
            example:
              amount: 49
              currency: "USD"
  /payment/lookup:
    get:
      tags:
        - "Payments"
      summary: "Look up a payment"
      responses:
        "200":
          description: "data: tid, status, amount, amount_usd, currency, created_at, expires_at, expires_in; once a coin is chosen also coin, crypto_amount, received, remaining, partial."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Success"
        default:
          description: "Error — see the `error` message and HTTP status."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      parameters:
        -
          name: "tid"
          in: "query"
          required: true
          schema:
            type: "string"
          description: "The payment id."
  /payment/cancel:
    post:
      tags:
        - "Payments"
      summary: "Cancel a payment"
      responses:
        "200":
          description: "data: tid, status. Only CREATED/PENDING can be cancelled (else 409)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Success"
        default:
          description: "Error — see the `error` message and HTTP status."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        -
          ApiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: "object"
              properties:
                tid:
                  type: "string"
                  description: "The payment id to cancel."
              required:
                - "tid"
  /payment/receipt:
    post:
      tags:
        - "Payments"
      summary: "Email a buyer receipt"
      responses:
        "200":
          description: "data: tid. The payment must be COMPLETED."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Success"
        default:
          description: "Error — see the `error` message and HTTP status."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: "object"
              properties:
                tid:
                  type: "string"
                  description: "A completed payment id."
                email:
                  type: "string"
                  description: "Recipient email."
              required:
                - "tid"
                - "email"
  /payment/recheck:
    post:
      tags:
        - "Payments"
      summary: "Force a status re-check"
      responses:
        "200":
          description: "data.status / data.settled are authoritative; may include cooldown, retry_after, or partial-payment detail."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Success"
        default:
          description: "Error — see the `error` message and HTTP status."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: "object"
              properties:
                tid:
                  type: "string"
                  description: "The payment id to re-check against the processor."
              required:
                - "tid"
  /transactions:
    get:
      tags:
        - "Payments"
      summary: "List transactions"
      responses:
        "200":
          description: "Paginated. Row: tid, status, amount, currency, amount_usd, buyer_pays_fees, metadata, created_at. role=platform rows add commission fields."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Success"
        default:
          description: "Error — see the `error` message and HTTP status."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        -
          ApiKey: []
      parameters:
        -
          name: "page"
          in: "query"
          required: false
          schema:
            type: "integer"
          description: "1-based page (50 per page)."
        -
          name: "status"
          in: "query"
          required: false
          schema:
            type: "string"
            enum:
              - "CREATED"
              - "PENDING"
              - "COMPLETED"
              - "EXPIRED"
              - "CANCELLED"
          description: "Filter by status."
        -
          name: "sort"
          in: "query"
          required: false
          schema:
            type: "string"
            enum:
              - "date"
              - "status"
          description: "Sort order."
        -
          name: "role"
          in: "query"
          required: false
          schema:
            type: "string"
            enum:
              - "merchant"
              - "platform"
          description: "merchant (default) or platform (platform accounts only)."
  /payment-links:
    get:
      tags:
        - "Payment links"
      summary: "List payment links"
      responses:
        "200":
          description: "data: array of links (up to 50)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Success"
        default:
          description: "Error — see the `error` message and HTTP status."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        -
          ApiKey: []
    post:
      tags:
        - "Payment links"
      summary: "Create a payment link"
      responses:
        "200":
          description: "data: slug, url, title, mode, amount, currency, pay_currency, pay_network, active, created_at."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Success"
        default:
          description: "Error — see the `error` message and HTTP status."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        -
          ApiKey: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: "object"
              properties:
                title:
                  type: "string"
                  description: "Display title."
                mode:
                  type: "string"
                  description: "fixed (default) or open (customer enters the amount)."
                  enum:
                    - "fixed"
                    - "open"
                amount:
                  type: "number"
                  description: "Required for fixed mode."
                currency:
                  type: "string"
                  description: "Fiat pricing currency (default USD)."
                pay_currency:
                  type: "string"
                  description: "Pin the pay-in coin."
                pay_network:
                  type: "string"
                  description: "Pin the pay-in network."
                success_url:
                  type: "string"
                  description: "Buyer redirect after payment."
                webhook_url:
                  type: "string"
                  description: "Signed webhook URL for payments from this link."
  /balance:
    get:
      tags:
        - "Account"
      summary: "Get wallet balance"
      responses:
        "200":
          description: "data: currency=\"USD\", available, pending, lifetime_credited."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Success"
        default:
          description: "Error — see the `error` message and HTTP status."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        -
          ApiKey: []
  /account:
    get:
      tags:
        - "Account"
      summary: "Get account info"
      responses:
        "200":
          description: "data: account_id (usr_…), business_name, email, is_activated, fee_percent, fixed_fee, referral_code, default_webhook, default_success, default_cancel, created_at."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Success"
        default:
          description: "Error — see the `error` message and HTTP status."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        -
          ApiKey: []
  /refund/create:
    post:
      tags:
        - "Refunds"
      summary: "Create a refund"
      responses:
        "200":
          description: "data: refund_id, status=\"REQUESTED\", tid, claim_url, created_at. The customer picks coin/network + return address via claim_url."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Success"
        default:
          description: "Error — see the `error` message and HTTP status."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        -
          ApiKey: []
      parameters:
        -
          name: "Idempotency-Key"
          in: "header"
          required: false
          schema:
            type: "string"
          description: "Optional client key; a replay within 24h returns the original result with `Idempotency-Replayed: true`."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: "object"
              properties:
                tid:
                  type: "string"
                  description: "A completed payment to refund."
                amount:
                  type: "number"
                  description: "USD amount; omit or 0 for the full remaining amount."
                email:
                  type: "string"
                  description: "Where to send the claim link (defaults to the stored buyer email)."
                reason:
                  type: "string"
                  description: "Optional reason stored on the refund."
              required:
                - "tid"
  /refunds:
    get:
      tags:
        - "Refunds"
      summary: "List refunds"
      responses:
        "200":
          description: "Paginated. Row: refund_id, tid, amount_usd, status, reason, customer_email, tx_hash, created_at."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Success"
        default:
          description: "Error — see the `error` message and HTTP status."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        -
          ApiKey: []
      parameters:
        -
          name: "page"
          in: "query"
          required: false
          schema:
            type: "integer"
          description: "1-based page."
        -
          name: "status"
          in: "query"
          required: false
          schema:
            type: "string"
            enum:
              - "REQUESTED"
              - "PROCESSING"
              - "COMPLETED"
              - "REJECTED"
              - "CANCELLED"
          description: "Filter by status."
  /rates:
    get:
      tags:
        - "Market data"
      summary: "All exchange rates"
      responses:
        "200":
          description: "data: base=\"USD\", rates={COIN:usd_value,…}, count."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Success"
        default:
          description: "Error — see the `error` message and HTTP status."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /rates/{coin}:
    get:
      tags:
        - "Market data"
      summary: "Rate for one coin"
      responses:
        "200":
          description: "data: currency, usd_rate, base=\"USD\". Unknown coin → 404."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Success"
        default:
          description: "Error — see the `error` message and HTTP status."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      parameters:
        -
          name: "coin"
          in: "path"
          required: true
          schema:
            type: "string"
          description: "Coin ticker, e.g. BTC."
  /convert:
    get:
      tags:
        - "Market data"
      summary: "Convert an amount"
      responses:
        "200":
          description: "data: from, to, amount, result, rate."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Success"
        default:
          description: "Error — see the `error` message and HTTP status."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      parameters:
        -
          name: "from"
          in: "query"
          required: true
          schema:
            type: "string"
          description: "Source currency."
        -
          name: "to"
          in: "query"
          required: true
          schema:
            type: "string"
          description: "Target currency."
        -
          name: "amount"
          in: "query"
          required: false
          schema:
            type: "number"
          description: "Amount to convert (default 1)."
  /payout/create:
    post:
      tags:
        - "Payouts"
      summary: "Request a withdrawal"
      responses:
        "200":
          description: "data: payout_id, status=\"PROCESSING\", amount, platform_fee, receive_estimate, currency, network, address. Ambiguous processor failure → 502 (funds may have sent; do not retry)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Success"
        default:
          description: "Error — see the `error` message and HTTP status."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        -
          WithdrawalKey: []
      parameters:
        -
          name: "Idempotency-Key"
          in: "header"
          required: false
          schema:
            type: "string"
          description: "Optional client key; a replay within 24h returns the original result with `Idempotency-Replayed: true`."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: "object"
              properties:
                amount:
                  type: "number"
                  description: "USD amount to withdraw."
                currency:
                  type: "string"
                  description: "Payout coin (default USDT)."
                network:
                  type: "string"
                  description: "Payout network (default TRON)."
                address:
                  type: "string"
                  description: "Destination address (required unless address_id is given)."
                address_id:
                  type: "integer"
                  description: "Saved payout-address id; overrides currency/network/address."
              required:
                - "amount"
  /payout/lookup:
    get:
      tags:
        - "Payouts"
      summary: "Get a payout"
      responses:
        "200":
          description: "data: payout_id, status, amount, platform_fee, receive_estimate, currency, network, address, tx_hash, created_at."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Success"
        default:
          description: "Error — see the `error` message and HTTP status."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        -
          ApiKey: []
      parameters:
        -
          name: "id"
          in: "query"
          required: true
          schema:
            type: "integer"
          description: "The payout id."
  /payout/estimate:
    get:
      tags:
        - "Payouts"
      summary: "Estimate a payout"
      responses:
        "200":
          description: "data: amount, platform_fee, network_fee, receive_estimate, currency, network."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Success"
        default:
          description: "Error — see the `error` message and HTTP status."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        -
          ApiKey: []
      parameters:
        -
          name: "amount"
          in: "query"
          required: true
          schema:
            type: "number"
          description: "USD amount."
        -
          name: "currency"
          in: "query"
          required: false
          schema:
            type: "string"
          description: "Payout coin (default USDT)."
        -
          name: "network"
          in: "query"
          required: false
          schema:
            type: "string"
          description: "Payout network (default TRON)."
  /payouts:
    get:
      tags:
        - "Payouts"
      summary: "List payouts"
      responses:
        "200":
          description: "Paginated. Row: payout_id, status, amount, platform_fee, receive_estimate, currency, network, address, tx_hash, created_at."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Success"
        default:
          description: "Error — see the `error` message and HTTP status."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        -
          ApiKey: []
      parameters:
        -
          name: "page"
          in: "query"
          required: false
          schema:
            type: "integer"
          description: "1-based page."
        -
          name: "status"
          in: "query"
          required: false
          schema:
            type: "string"
            enum:
              - "PENDING"
              - "PROCESSING"
              - "COMPLETED"
              - "REJECTED"
          description: "Filter by status."
  /payout-addresses:
    get:
      tags:
        - "Payouts"
      summary: "List payout addresses"
      responses:
        "200":
          description: "data: array of {id, label, currency, network, address, is_default}."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Success"
        default:
          description: "Error — see the `error` message and HTTP status."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        -
          ApiKey: []
    post:
      tags:
        - "Payouts"
      summary: "Add a payout address"
      responses:
        "200":
          description: "data: the full updated address book."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Success"
        default:
          description: "Error — see the `error` message and HTTP status."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        -
          ApiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: "object"
              properties:
                currency:
                  type: "string"
                  description: "Coin, e.g. USDT."
                network:
                  type: "string"
                  description: "Network, e.g. TRON."
                address:
                  type: "string"
                  description: "Destination address."
                label:
                  type: "string"
                  description: "Friendly label."
                make_default:
                  type: "boolean"
                  description: "Set as the default destination."
              required:
                - "currency"
                - "network"
                - "address"
    delete:
      tags:
        - "Payouts"
      summary: "Delete a payout address"
      responses:
        "200":
          description: "data: { id }."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Success"
        default:
          description: "Error — see the `error` message and HTTP status."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        -
          ApiKey: []
      parameters:
        -
          name: "id"
          in: "query"
          required: true
          schema:
            type: "integer"
          description: "The address id to delete."
  /transfer/create:
    post:
      tags:
        - "Transfers"
      summary: "Transfer to another account"
      responses:
        "200":
          description: "data: transfer_id, status=\"COMPLETED\", amount, currency=\"USD\", recipient, recipient_name, note, created_at."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Success"
        default:
          description: "Error — see the `error` message and HTTP status."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        -
          WithdrawalKey: []
      parameters:
        -
          name: "Idempotency-Key"
          in: "header"
          required: false
          schema:
            type: "string"
          description: "Optional client key; a replay within 24h returns the original result with `Idempotency-Replayed: true`."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: "object"
              properties:
                recipient:
                  type: "string"
                  description: "Recipient account id (usr_…). Aliases: to, user_id."
                amount:
                  type: "number"
                  description: "USD amount to send."
                note:
                  type: "string"
                  description: "Optional note (≤255)."
              required:
                - "recipient"
                - "amount"
  /transfer/lookup:
    get:
      tags:
        - "Transfers"
      summary: "Get a transfer"
      responses:
        "200":
          description: "data: transfer_id, direction, amount, currency=\"USD\", counterparty, note, created_at."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Success"
        default:
          description: "Error — see the `error` message and HTTP status."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        -
          ApiKey: []
      parameters:
        -
          name: "id"
          in: "query"
          required: true
          schema:
            type: "string"
          description: "Transfer ref (txf_…) or numeric id."
  /transfers:
    get:
      tags:
        - "Transfers"
      summary: "List transfers"
      responses:
        "200":
          description: "Paginated. Row: transfer_id, direction, amount, currency, counterparty, note, created_at."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Success"
        default:
          description: "Error — see the `error` message and HTTP status."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        -
          ApiKey: []
      parameters:
        -
          name: "page"
          in: "query"
          required: false
          schema:
            type: "integer"
          description: "1-based page."
        -
          name: "direction"
          in: "query"
          required: false
          schema:
            type: "string"
            enum:
              - "in"
              - "out"
          description: "Filter by direction."
  /swap/currencies:
    get:
      tags:
        - "Exchange"
      summary: "List swap currencies"
      responses:
        "200":
          description: "data: coins, nets, min_usd, max_usd, svc_fee_pct, fixed_fee_pct, lock_minutes."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Success"
        default:
          description: "Error — see the `error` message and HTTP status."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /swap/estimate:
    get:
      tags:
        - "Exchange"
      summary: "Quote a swap"
      responses:
        "200":
          description: "data: rate, receive, receive_float, receive_fixed, price_from, price_to, deposit_usd, amount_ok, limits, fees."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Success"
        default:
          description: "Error — see the `error` message and HTTP status."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      parameters:
        -
          name: "from"
          in: "query"
          required: true
          schema:
            type: "string"
          description: "Send coin, e.g. BTC."
        -
          name: "from_network"
          in: "query"
          required: false
          schema:
            type: "string"
          description: "Send network (defaults to the coin)."
        -
          name: "to"
          in: "query"
          required: true
          schema:
            type: "string"
          description: "Receive coin, e.g. ETH."
        -
          name: "to_network"
          in: "query"
          required: false
          schema:
            type: "string"
          description: "Receive network (defaults to the coin)."
        -
          name: "amount"
          in: "query"
          required: false
          schema:
            type: "number"
          description: "Send amount."
        -
          name: "type"
          in: "query"
          required: false
          schema:
            type: "string"
            enum:
              - "float"
              - "fixed"
          description: "float (default) or fixed (+ locked rate)."
  /swap/create:
    post:
      tags:
        - "Exchange"
      summary: "Create a swap"
      responses:
        "200":
          description: "data: tracking_id, status, deposit_address, deposit_expires_at, amount_to, rate, payout_address, … (swap publicView)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Success"
        default:
          description: "Error — see the `error` message and HTTP status."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: "object"
              properties:
                from:
                  type: "string"
                  description: "Send coin."
                from_network:
                  type: "string"
                  description: "Send network."
                to:
                  type: "string"
                  description: "Receive coin."
                to_network:
                  type: "string"
                  description: "Receive network."
                amount:
                  type: "number"
                  description: "Send amount."
                type:
                  type: "string"
                  description: "float or fixed."
                  enum:
                    - "float"
                    - "fixed"
                payout_address:
                  type: "string"
                  description: "Where to receive the `to` coin."
                refund_address:
                  type: "string"
                  description: "Where to refund on error (defaults to the sending address)."
                referral_wallet_address:
                  type: "string"
                  description: "Referral wallet — earns 50% of the service fee."
                referral_wallet_to:
                  type: "string"
                  description: "Referral payout coin."
                referral_wallet_network:
                  type: "string"
                  description: "Referral payout network."
              required:
                - "from"
                - "to"
                - "payout_address"
  /swap/status:
    get:
      tags:
        - "Exchange"
      summary: "Track a swap"
      responses:
        "200":
          description: "data: swap publicView (status, amounts, deposit/payout addresses, txids, expiry)."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Success"
        default:
          description: "Error — see the `error` message and HTTP status."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      parameters:
        -
          name: "id"
          in: "query"
          required: true
          schema:
            type: "string"
          description: "The tracking id (SWP-…). Alias: tracking_id."
  /swap/receipt:
    post:
      tags:
        - "Exchange"
      summary: "Email a swap receipt"
      responses:
        "200":
          description: "data: { sent: true }. Available after the swap ends."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Success"
        default:
          description: "Error — see the `error` message and HTTP status."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: "object"
              properties:
                id:
                  type: "string"
                  description: "Tracking id (alias tracking_id)."
                email:
                  type: "string"
                  description: "Recipient email."
              required:
                - "id"
                - "email"
components:
  securitySchemes:
    ApiKey:
      type: "http"
      scheme: "bearer"
      description: "Merchant secret API key (sk_live_…)."
    WithdrawalKey:
      type: "http"
      scheme: "bearer"
      description: "Withdrawal key (wk_live_…) — required for money-out endpoints."
  schemas:
    Success:
      type: "object"
      properties:
        status:
          type: "string"
          example: "success"
        message:
          type: "string"
        data:
          type: "object"
          additionalProperties: true
        timestamp:
          type: "integer"
          description: "Unix time."
      required:
        - "status"
        - "data"
        - "timestamp"
    Error:
      type: "object"
      properties:
        status:
          type: "string"
          example: "failed"
        error:
          type: "string"
        timestamp:
          type: "integer"
      required:
        - "status"
        - "error"
        - "timestamp"
