{
  "openapi": "3.1.0",
  "info": {
    "title": "MapleMarkets Exchange & Escrow API",
    "version": "1.0.0",
    "description": "Institutional machine-readable API for MapleMarkets currency exchange spot rates, 100% Free Market tax-absorbed calculations, godly gear crafting variances, and 2-of-3 multisig escrow telemetry for 2005 MMORPG launch economies.",
    "contact": {
      "name": "MapleMarkets Systems Operations",
      "url": "https://maplemarketssite.vercel.app/faq",
      "email": "support@maplemarkets.xyz"
    },
    "license": {
      "name": "Proprietary Commercial API",
      "url": "https://maplemarketssite.vercel.app/trust-ledger"
    }
  },
  "servers": [
    {
      "url": "https://maplemarketssite.vercel.app",
      "description": "Production Edge Gateway"
    }
  ],
  "paths": {
    "/api/health": {
      "get": {
        "summary": "System Health & Courier Heartbeat",
        "description": "Returns edge system health, Free Market Channel 1 room courier operational statuses, and database latency.",
        "operationId": "getSystemHealth",
        "responses": {
          "200": {
            "description": "Operational telemetry",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthStatus"
                }
              }
            }
          }
        }
      }
    },
    "/api/chat": {
      "post": {
        "summary": "AI Concierge Consultation (Cody)",
        "description": "Conversational assistant endpoint providing live meso price quotes, quest requirements, scroll probability analysis, and escrow guidance.",
        "operationId": "consultCodyAI",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChatRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Concierge streaming or JSON response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChatResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/crypto/verify-transaction": {
      "post": {
        "summary": "Verify Blockchain Payment",
        "description": "Verifies on-chain payment TXID broadcast for an active order across USDT, SOL, BTC, or ETH networks.",
        "operationId": "verifyCryptoPayment",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VerifyTransactionRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Payment confirmed and escrow state locked",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VerifyTransactionResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/crypto/verify/{orderIdentifier}": {
      "get": {
        "summary": "Get Escrow Order Status & PoTx",
        "description": "Retrieves cryptographic Proof-of-Transaction (PoTx) hash, courier assignment, and settlement verification for an order.",
        "operationId": "getOrderStatus",
        "parameters": [
          {
            "name": "orderIdentifier",
            "in": "path",
            "required": true,
            "description": "Unique order UUID or transaction identifier",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Detailed order escrow state",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderStatus"
                }
              }
            }
          },
          "404": {
            "description": "Order identifier not found"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "HealthStatus": {
        "type": "object",
        "properties": {
          "status": { "type": "string", "example": "healthy" },
          "uptime": { "type": "number", "example": 99.98 },
          "couriersOnline": { "type": "integer", "example": 22 },
          "activeWorld": { "type": "string", "example": "Fresh Launch" },
          "timestamp": { "type": "string", "format": "date-time" }
        },
        "required": ["status", "uptime", "couriersOnline"]
      },
      "ChatRequest": {
        "type": "object",
        "properties": {
          "message": { "type": "string", "example": "How much for 100M on Classic World and is tax covered?" },
          "world": { "type": "string", "example": "Classic World (Launch Oct 21)" },
          "sessionId": { "type": "string" }
        },
        "required": ["message"]
      },
      "ChatResponse": {
        "type": "object",
        "properties": {
          "reply": { "type": "string" },
          "suggestedActions": {
            "type": "array",
            "items": { "type": "string" }
          }
        },
        "required": ["reply"]
      },
      "VerifyTransactionRequest": {
        "type": "object",
        "properties": {
          "orderId": { "type": "string" },
          "txHash": { "type": "string", "example": "0x4a8f9c1b3e2d..." },
          "network": { "type": "string", "enum": ["USDT_TRC20", "USDT_BEP20", "SOL", "BTC", "ETH"] },
          "amount": { "type": "number" }
        },
        "required": ["orderId", "txHash", "network"]
      },
      "VerifyTransactionResponse": {
        "type": "object",
        "properties": {
          "verified": { "type": "boolean" },
          "orderId": { "type": "string" },
          "escrowStatus": { "type": "string", "enum": ["funded", "courier_dispatched", "completed"] },
          "potxHash": { "type": "string" }
        },
        "required": ["verified", "orderId", "escrowStatus"]
      },
      "OrderStatus": {
        "type": "object",
        "properties": {
          "orderId": { "type": "string" },
          "world": { "type": "string" },
          "mesoAmountM": { "type": "number" },
          "grossDeliveredM": { "type": "number" },
          "taxAbsorbedM": { "type": "number" },
          "escrowState": { "type": "string" },
          "courierMule": { "type": "string" },
          "meetingRoom": { "type": "string" },
          "potxHash": { "type": "string" }
        },
        "required": ["orderId", "world", "escrowState"]
      }
    }
  }
}