{
  "openapi": "3.1.0",
  "info": {
    "title": "Sovereign Token Arbitrage Analytical Optimizer & MCP Node API",
    "description": "Programmatic discovery, zero-copy columnar in-memory database query compiler, and token arbitrage mathematical optimization service. Designed to process remote cloud dataset pointers, perform statistical compilation, and return compressed analytical summaries to AWS AI Agents over secure x402 on-chain standard channels.",
    "version": "1.2.0",
    "contact": {
      "name": "Sovereign Exchange Labs Support",
      "url": "https://newdataretrieve.org/instructions.txt"
    }
  },
  "servers": [
    {
      "url": "https://newdataretrieve.org",
      "description": "Production Autonomous Hub"
    }
  ],
  "paths": {
    "/api/keys/provision": {
      "post": {
        "summary": "Autonomous API Key Provisioning",
        "description": "Mints a unique API key for paying bots. Rejection yields an HTTP 402 with pay-to blockchain instructions. Providing authorized proof registers and returns the API key.",
        "operationId": "provisionApiKey",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "owner": {
                    "type": "string",
                    "description": "Human or machine identifier representing the service bot.",
                    "example": "My-Sovereign-Agent-Bot"
                  }
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "x-payment-verified",
            "in": "header",
            "required": false,
            "description": "On-chain clearance affirmation header.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "x-payment-proof",
            "in": "header",
            "required": false,
            "description": "On-chain transaction hash or verifiable proof representing payment of 5.00 USD.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Key successfully provisioned",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "success"
                    },
                    "api_key": {
                      "type": "string",
                      "example": "sk_mcp_3k9Jn81LdpWq8sKlP04eMxYz"
                    },
                    "owner": {
                      "type": "string",
                      "example": "My-Sovereign-Agent-Bot"
                    },
                    "message": {
                      "type": "string",
                      "example": "API key provisioned autonomously. Supply as 'Authorization: Bearer <key>' or 'x-api-key: <key>' to GET /api/mcp_exchange"
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "Payment Required for Key Generation",
            "headers": {
              "X-402-Payment-Required": {
                "schema": {
                  "type": "string",
                  "example": "5.00 USD"
                }
              },
              "X-402-Wallet": {
                "schema": {
                  "type": "string",
                  "example": "0x13B4388B5760F1BafCB439e6F7CA9A994B02CA04"
                }
              },
              "X-402-Method": {
                "schema": {
                  "type": "string",
                  "example": "x402-key-minting-v1"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "example": "Payment Required"
                    },
                    "protocol": {
                      "type": "string",
                      "example": "x402"
                    },
                    "amount": {
                      "type": "string",
                      "example": "5.00"
                    },
                    "currency": {
                      "type": "string",
                      "example": "USD"
                    },
                    "address": {
                      "type": "string",
                      "example": "0x13B4388B5760F1BafCB439e6F7CA9A994B02CA04"
                    },
                    "message": {
                      "type": "string",
                      "example": "Autonomous AI Agent Detected: Provisioning an API key requires a protocol-payment of 5.00 USD."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/mcp_exchange": {
      "get": {
        "summary": "Retrieve Authenticated Exchange Schema",
        "description": "High-speed JSON endpoint to pull the live matching list of active vendors and historical tracking logs. Accessible only with a provisioned developer API key.",
        "operationId": "getAuthenticatedExchange",
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "HeaderApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Exchange registry retrieval success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExchangeData"
                }
              }
            }
          },
          "401": {
            "description": "Invalid or missing API key"
          }
        }
      }
    },
    "/mcp_exchange.json": {
      "get": {
        "summary": "Public Exchange Registry state",
        "description": "Serves the list of active MCP placements and audit logs.",
        "operationId": "getPublicExchange",
        "parameters": [
          {
            "name": "protocol",
            "in": "query",
            "required": false,
            "description": "Query option to pull lists natively. For REST formats use 'rest-list'.",
            "schema": {
              "type": "string",
              "enum": ["rest-list"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Current exchange index",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExchangeData"
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Submit Bid or Call RPC Tool",
        "description": "Integrity point supporting both programmatic flat-bids (using parameter `?protocol=rest-bid`) and standard JSON-RPC 2.0 requests.",
        "operationId": "postExchangeAction",
        "parameters": [
          {
            "name": "protocol",
            "in": "query",
            "required": false,
            "description": "Set to 'rest-bid' for posting vendor bid registries directly.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/BidSubmission"
                  },
                  {
                    "$ref": "#/components/schemas/JsonRpcRequest"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Bid registered successfully or RPC result delivered",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/rfq": {
      "post": {
        "summary": "Initiate RFQ Protocol",
        "description": "Enables machine buyers to request real-time pricing and terms against particular tasks.",
        "operationId": "initiateRfq",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "RFQ successfully initialized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "quote_id": {
                      "type": "string",
                      "example": "Q-8Z9XK1"
                    },
                    "status": {
                      "type": "string",
                      "example": "RFQ_RECEIVED"
                    },
                    "timestamp": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "message": {
                      "type": "string",
                      "example": "Request for quote protocol initiated."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/health": {
      "get": {
        "summary": "Health Check Status",
        "description": "Returns current vault cluster status and identification moniker.",
        "operationId": "getHealth",
        "responses": {
          "200": {
            "description": "Service is operational",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "ok"
                    },
                    "node": {
                      "type": "string",
                      "example": "NE-Vault-01"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "sk_mcp_...",
        "description": "Bearer token with authorization credentials received from Provisioning flow"
      },
      "HeaderApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "Custom API authorization key header alternative"
      }
    },
    "schemas": {
      "ExchangeData": {
        "type": "object",
        "properties": {
          "last_updated": {
            "type": "string",
            "format": "date-time",
            "example": "2026-05-26T15:36:10Z"
          },
          "protocol_standard": {
            "type": "string",
            "example": "MCP-V1.0-AWS-ACTIVE"
          },
          "vendors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/VendorRecord"
            }
          },
          "logs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ExchangeLog"
            }
          }
        }
      },
      "VendorRecord": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "v-j8a9qfbc"
          },
          "name": {
            "type": "string",
            "example": "Sovereign Inference Labs"
          },
          "description": {
            "type": "string",
            "example": "Premium non-synthetic fine-tunes on dedicated AWS rigs."
          },
          "endpoint": {
            "type": "string",
            "example": "https://api.sovereigninference.net/v1/mcp"
          },
          "api_identifier": {
            "type": "string",
            "example": "A3513",
            "description": "API dimension identifier used for AWS usage tracking and programmatic billing."
          },
          "aws_usage_dimension": {
            "type": "string",
            "example": "A3513",
            "description": "The exact AWS Marketplace product usage dimension string."
          },
          "bid_per_request_usd": {
            "type": "number",
            "example": 0.25
          },
          "wallet_address": {
            "type": "string",
            "example": "0x4a6fc24b86866224b86866224b86866224b86866"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "status": {
            "type": "string",
            "example": "active"
          }
        }
      },
      "ExchangeLog": {
        "type": "object",
        "properties": {
          "timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "bot_type": {
            "type": "string",
            "example": "buyer"
          },
          "agent_string": {
            "type": "string",
            "example": "Authenticated-Agent/1.0"
          },
          "action": {
            "type": "string",
            "example": "api_exchange_access"
          },
          "details": {
            "type": "string",
            "example": "Served exchange schema to authorized key owner"
          }
        }
      },
      "BidSubmission": {
        "type": "object",
        "required": ["name", "endpoint", "bid_per_request_usd", "wallet_address"],
        "properties": {
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "endpoint": {
            "type": "string"
          },
          "bid_per_request_usd": {
            "type": "number"
          },
          "wallet_address": {
            "type": "string"
          }
        }
      },
      "JsonRpcRequest": {
        "type": "object",
        "required": ["jsonrpc", "method", "id"],
        "properties": {
          "jsonrpc": {
            "type": "string",
            "enum": ["2.0"]
          },
          "method": {
            "type": "string"
          },
          "id": {
            "type": "integer"
          },
          "params": {
            "type": "object"
          }
        }
      }
    }
  }
}