{
  "openapi": "3.1.0",
  "info": {
    "title": "covr maker HTTP routes",
    "version": "0.1.1+bb3e1c9e",
    "description": "The HTTP routes a market-making desk uses on covr's gateway host: one token-checked RFQ read and two public status routes. Prose reference: https://docs.covr.markets/#reference.gateway.overview",
    "x-covr-source": {
      "commit": "bb3e1c9e5dd2e7794eddc9b985b95756d2957a32",
      "sdkVersion": "0.1.1"
    }
  },
  "servers": [
    {
      "url": "https://{host}",
      "description": "The host covr gives your desk (the same host as your wss:// URL).",
      "variables": {
        "host": {
          "default": "provided-by-covr",
          "description": "Provided by covr."
        }
      }
    }
  ],
  "paths": {
    "/api/rfqs/{id}": {
      "get": {
        "operationId": "getRfq",
        "summary": "Read one RFQ: market, customer wallet, deadlines, status.",
        "description": "Read it once per RFQ, as soon as the rfq event arrives: bids close 3000 ms after creation. The gateway forgets an RFQ about 120 s after creation. A desk sees the quote fields only for its own admitted quote. Through covr's public endpoint the gateway must answer within 5000 ms and in at most 65536 bytes, else 502.",
        "security": [
          {
            "bearer": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "RFQ id (UUID).",
            "schema": {
              "type": "string",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The RFQ snapshot.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RfqSnapshot"
                }
              }
            }
          },
          "401": {
            "description": "No token, or an unknown token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Unauthorized"
                }
              }
            }
          },
          "404": {
            "description": "Unknown RFQ, an RFQ on an asset your token does not allow, or a malformed path.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "RFQ not found"
                }
              }
            }
          },
          "500": {
            "description": "The read failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "RFQ read failed"
                }
              }
            }
          },
          "502": {
            "description": "covr's public endpoint could not reach the gateway in time.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Gateway unavailable"
                }
              }
            }
          },
          "503": {
            "description": "The gateway is stopping.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Gateway stopping"
                }
              }
            }
          }
        },
        "x-timeouts": {
          "requestHeadersMs": 10000,
          "wholeRequestMs": 15000,
          "publicEndpointUpstreamMs": 5000
        }
      }
    },
    "/status/quotes": {
      "get": {
        "operationId": "getQuoteStatus",
        "summary": "Is covr's own maker able to quote customers right now?",
        "security": [],
        "description": "No token. Re-read at most once a second. Responses carry Cache-Control: no-store.",
        "responses": {
          "200": {
            "description": "ready is true.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicQuoteStatus"
                }
              }
            }
          },
          "400": {
            "description": "The URL had a query string.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicQuoteStatus"
                }
              }
            }
          },
          "405": {
            "description": "Not GET.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicQuoteStatus"
                }
              }
            }
          },
          "503": {
            "description": "ready is false, or the status could not be read.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicQuoteStatus"
                }
              }
            }
          }
        }
      }
    },
    "/status/health": {
      "get": {
        "operationId": "getHealth",
        "summary": "Liveness for uptime monitors.",
        "security": [],
        "description": "No token. Tolerates short dips in quote readiness; unhealthy once not ready continuously past a grace period, or at once if the quote publisher stopped.",
        "responses": {
          "200": {
            "description": "healthy is true.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicHealth"
                }
              }
            }
          },
          "400": {
            "description": "The URL had a query string.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicHealth"
                }
              }
            }
          },
          "405": {
            "description": "Not GET.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicHealth"
                }
              }
            }
          },
          "503": {
            "description": "healthy is false.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicHealth"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "RfqSnapshot": {
        "description": "One RFQ as GET /api/rfqs/{id} returns it to a desk. A desk sees the quote fields only for its own admitted quote. Unknown fields may be added: ignore them.",
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
          },
          "kind": {
            "type": "string",
            "enum": [
              "open",
              "position_sale",
              "early_close"
            ]
          },
          "position": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$"
          },
          "status": {
            "type": "string",
            "examples": [
              "collecting",
              "finalizing",
              "quoted",
              "no_quote",
              "expired"
            ]
          },
          "market": {
            "type": "string",
            "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$",
            "description": "The MarketV3 account. Sign in its EIP-712 domain."
          },
          "preparationFamily": {
            "type": "string",
            "examples": [
              "ordinary-v3",
              "restricted-v3"
            ]
          },
          "closesAt": {
            "type": "integer",
            "description": "Bid collection ends, unix ms."
          },
          "hardDeadline": {
            "type": "integer",
            "description": "No quote is admitted at or after this, unix ms."
          },
          "bidCount": {
            "type": "integer"
          },
          "wallet": {
            "type": "string",
            "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$",
            "description": "The customer's Solana wallet, from the RFQ snapshot."
          },
          "request": {
            "$ref": "#/components/schemas/RfqRequest"
          },
          "stockSelection": {},
          "quote": {
            "$ref": "#/components/schemas/QuoteV2"
          }
        },
        "required": [
          "id",
          "kind",
          "position",
          "status",
          "market",
          "closesAt",
          "hardDeadline",
          "wallet",
          "request"
        ],
        "additionalProperties": true
      },
      "RfqRequest": {
        "description": "The RFQ request: the instrument terms the customer asked for.",
        "type": "object",
        "properties": {
          "asset": {
            "type": "string",
            "pattern": "^0x[0-9a-f]{40}$"
          },
          "assetName": {
            "type": "string"
          },
          "chainId": {
            "type": "integer",
            "description": "Always 2000000001: a venue tag for EIP-712, not an EVM chain."
          },
          "expiry": {
            "type": "integer",
            "description": "Option expiry, unix seconds."
          },
          "isPut": {
            "type": "boolean"
          },
          "isTakerBuy": {
            "type": "boolean"
          },
          "quantity": {
            "type": "string",
            "pattern": "^(0|[1-9][0-9]*)$",
            "description": "Collateral in whole tokens scaled by 10^18."
          },
          "strike": {
            "type": "string",
            "pattern": "^(0|[1-9][0-9]*)$",
            "description": "Strike in USD per whole token, scaled by 10^8."
          },
          "taker": {
            "type": "string",
            "pattern": "^0x[0-9a-f]{40}$"
          },
          "usd": {
            "type": "string",
            "pattern": "^0x[0-9a-f]{40}$"
          },
          "collateralAsset": {
            "type": "string",
            "pattern": "^0x[0-9a-f]{40}$"
          }
        },
        "required": [
          "asset",
          "assetName",
          "chainId",
          "expiry",
          "isPut",
          "isTakerBuy",
          "quantity",
          "strike",
          "taker",
          "usd",
          "collateralAsset"
        ],
        "additionalProperties": false
      },
      "QuoteV2": {
        "description": "Executable quote. EIP-712 primary type QuoteV2, signed in the market's domain.",
        "type": "object",
        "properties": {
          "assetAddress": {
            "type": "string",
            "pattern": "^0x[0-9a-f]{40}$"
          },
          "chainId": {
            "type": "integer",
            "description": "Always 2000000001: a venue tag for EIP-712, not an EVM chain."
          },
          "expiry": {
            "type": "integer",
            "description": "Option expiry, unix seconds."
          },
          "isPut": {
            "type": "boolean"
          },
          "isTakerBuy": {
            "type": "boolean"
          },
          "quantity": {
            "type": "string",
            "pattern": "^(0|[1-9][0-9]*)$",
            "description": "Collateral in whole tokens scaled by 10^18."
          },
          "strike": {
            "type": "string",
            "pattern": "^(0|[1-9][0-9]*)$",
            "description": "Strike in USD per whole token, scaled by 10^8."
          },
          "maker": {
            "type": "string",
            "pattern": "^0x[0-9a-fA-F]{40}$",
            "description": "Your registered quote key (secp256k1 address). Must be the maker your token is bound to."
          },
          "nonce": {
            "type": "string",
            "pattern": "^(0|[1-9][0-9]*)$",
            "description": "u64 below 2^64 - 1. Names the one position this quote can open. Never reuse one."
          },
          "price": {
            "type": "string",
            "pattern": "^(0|[1-9][0-9]*)$",
            "description": "Gross premium per one whole collateral token, in USDC scaled by 10^18. quantity x price / 10^30 must be a whole number of USDC atoms."
          },
          "validUntil": {
            "type": "integer",
            "description": "Unix seconds."
          },
          "usd": {
            "type": "string",
            "pattern": "^0x[0-9a-f]{40}$"
          },
          "collateralAsset": {
            "type": "string",
            "pattern": "^0x[0-9a-f]{40}$"
          },
          "signature": {
            "type": "string",
            "pattern": "^0x[0-9a-fA-F]{130}$"
          },
          "auctionId": {
            "type": "string",
            "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
          },
          "writer": {
            "type": "string",
            "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$",
            "description": "The customer's Solana wallet, from the RFQ snapshot."
          }
        },
        "required": [
          "assetAddress",
          "chainId",
          "expiry",
          "isPut",
          "isTakerBuy",
          "quantity",
          "strike",
          "maker",
          "nonce",
          "price",
          "validUntil",
          "usd",
          "collateralAsset",
          "signature",
          "auctionId",
          "writer"
        ],
        "additionalProperties": false,
        "x-eip712": {
          "primaryType": "QuoteV2",
          "fields": [
            {
              "name": "auctionId",
              "type": "bytes32"
            },
            {
              "name": "writer",
              "type": "bytes32"
            },
            {
              "name": "assetAddress",
              "type": "address"
            },
            {
              "name": "chainId",
              "type": "uint256"
            },
            {
              "name": "isPut",
              "type": "bool"
            },
            {
              "name": "strike",
              "type": "uint256"
            },
            {
              "name": "expiry",
              "type": "uint64"
            },
            {
              "name": "maker",
              "type": "address"
            },
            {
              "name": "nonce",
              "type": "uint64"
            },
            {
              "name": "price",
              "type": "uint256"
            },
            {
              "name": "quantity",
              "type": "uint256"
            },
            {
              "name": "isTakerBuy",
              "type": "bool"
            },
            {
              "name": "validUntil",
              "type": "uint64"
            },
            {
              "name": "usd",
              "type": "address"
            },
            {
              "name": "collateralAsset",
              "type": "address"
            }
          ]
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          }
        },
        "required": [
          "error"
        ]
      },
      "PublicQuoteStatus": {
        "description": "Whether covr's own maker can quote customers right now. Says nothing about your desk.",
        "type": "object",
        "properties": {
          "ready": {
            "type": "boolean"
          },
          "markets": {
            "type": "integer"
          },
          "priceAgeSec": {
            "type": [
              "integer",
              "null"
            ]
          },
          "checkedAt": {
            "type": "integer"
          }
        },
        "required": [
          "ready",
          "markets",
          "priceAgeSec",
          "checkedAt"
        ],
        "additionalProperties": false
      },
      "PublicHealth": {
        "description": "Liveness view of the quote status, for uptime monitors.",
        "type": "object",
        "properties": {
          "idle": {
            "const": true
          },
          "healthy": {
            "type": "boolean"
          },
          "notReadyForMs": {
            "type": "integer"
          },
          "ready": {
            "type": "boolean"
          },
          "markets": {
            "type": "integer"
          },
          "priceAgeSec": {
            "type": [
              "integer",
              "null"
            ]
          },
          "checkedAt": {
            "type": "integer"
          }
        },
        "required": [
          "healthy",
          "notReadyForMs",
          "ready",
          "markets",
          "priceAgeSec",
          "checkedAt"
        ],
        "additionalProperties": false
      }
    },
    "securitySchemes": {
      "bearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "Token issued by covr (prefix covr_mk_)."
      }
    }
  },
  "x-websocket-routes": {
    "publicEndpointPattern": "^\\/(?:maker|rfqs\\/0x[0-9a-f]{40})$",
    "rfqReadPattern": "^\\/api\\/rfqs\\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
    "spec": "/specs/maker-rfq.asyncapi.json"
  }
}
