{
  "openapi": "3.1.0",
  "info": {
    "title": "Kurs API",
    "version": "1.0.0",
    "summary": "Signed price feeds for Portaldot V3 and Ethereum Sepolia.",
    "description": "Read-only HTTP interface to Kurs. Every price here is also on chain: these endpoints read the contracts, sign fresh ERC-7412 bundles, or rebuild history from logs. Nothing is cached beyond the stated max-age. Public and unauthenticated: no API key.",
    "license": {
      "name": "MIT",
      "identifier": "MIT"
    },
    "contact": {
      "url": "https://github.com/PugarHuda/kurs"
    }
  },
  "servers": [
    {
      "url": "https://kurs-ten-zeta.vercel.app"
    }
  ],
  "tags": [
    {
      "name": "feeds",
      "description": "Feed catalogue and on-chain state"
    },
    {
      "name": "pull",
      "description": "ERC-7412 signed bundles"
    },
    {
      "name": "ops",
      "description": "Monitoring"
    }
  ],
  "paths": {
    "/api/feeds": {
      "get": {
        "tags": [
          "feeds"
        ],
        "operationId": "listFeeds",
        "summary": "Every feed with its id, parameters, sources and AggregatorV3 address per network",
        "responses": {
          "200": {
            "description": "Feed catalogue",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FeedList"
                }
              }
            }
          }
        }
      }
    },
    "/api/bundle": {
      "get": {
        "tags": [
          "pull"
        ],
        "operationId": "getBundle",
        "summary": "A freshly signed observation bundle and its ERC-7412 payload",
        "description": "Pass `payload` to `KursOracle.fulfillOracleQuery` on any chain running Kurs, e.g. inside `Multicall3.aggregate3` before the call that needs a fresh price.",
        "parameters": [
          {
            "$ref": "#/components/parameters/Pair"
          }
        ],
        "responses": {
          "200": {
            "description": "Signed bundle",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Bundle"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "503": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/health": {
      "get": {
        "tags": [
          "ops"
        ],
        "operationId": "getHealth",
        "summary": "Age of every feed's latest round on every network",
        "description": "200 when every feed is within twice its heartbeat (Portaldot: the 64-minute slot-aligned cadence), 503 otherwise.",
        "responses": {
          "200": {
            "description": "All feeds fresh",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Health"
                }
              }
            }
          },
          "503": {
            "description": "At least one feed stale",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Health"
                }
              }
            }
          }
        }
      },
      "head": {
        "summary": "Same status as GET, no body (for uptime monitors)",
        "responses": {
          "200": {
            "description": "every feed fresh"
          },
          "503": {
            "description": "a feed is stale or unreadable"
          }
        }
      }
    },
    "/api/substrate": {
      "get": {
        "tags": [
          "feeds"
        ],
        "operationId": "readViaSubstrate",
        "summary": "Every Portaldot feed read through the Substrate runtime API ReviveApi_call",
        "description": "Uses only the node WebSocket (state_call ReviveApi_call), no EVM RPC: the path a Polkadot wallet or polkadot.js client takes.",
        "responses": {
          "200": {
            "description": "Latest rounds at one block",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubstrateRead"
                }
              }
            }
          },
          "502": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/history": {
      "get": {
        "tags": [
          "feeds"
        ],
        "operationId": "getHistory",
        "summary": "Every round a feed has had, rebuilt from RoundUpdated logs",
        "description": "Covers history past the contract's 64-round ring buffer. Newest first.",
        "parameters": [
          {
            "name": "net",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "portaldot",
                "sepolia"
              ],
              "default": "portaldot"
            },
            "description": "Network. `network` and `chain` are accepted as aliases; an unknown value is a 400."
          },
          {
            "$ref": "#/components/parameters/Pair"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 5000,
              "default": 500
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Round history",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/History"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "502": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "description": "the pair is not configured on that network (e.g. GBP/USD on portaldot)"
          }
        }
      }
    },
    "/api/metrics": {
      "get": {
        "summary": "Prometheus metrics: feed age, answer, round id, freshness per chain, relayer gas balance",
        "operationId": "metrics",
        "responses": {
          "200": {
            "description": "Prometheus text exposition format 0.0.4",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/api/x402": {
      "get": {
        "summary": "The /api/bundle signed bundle behind an x402 paywall (0.001 USDC on Base Sepolia per bundle); /api/bundle stays free",
        "operationId": "x402Bundle",
        "parameters": [
          {
            "name": "pair",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "USD/IDR"
          },
          {
            "name": "X-PAYMENT",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "base64 JSON x402 v1 PaymentPayload (exact scheme, EIP-3009 authorization)"
          }
        ],
        "responses": {
          "200": {
            "description": "Paid: the signed bundle; X-PAYMENT-RESPONSE carries the settlement",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Bundle"
                }
              }
            }
          },
          "402": {
            "description": "Payment required: x402 v1 PaymentRequirements in accepts[]",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/quote": {
      "get": {
        "tags": [
          "feeds"
        ],
        "operationId": "getQuote",
        "summary": "Convert an amount with on-chain Kurs prices",
        "description": "A direct feed, its inverse, or a pivot through USD, read from KursOracle on chain. Every round used is returned with its age. With maxAge, a conversion that would use an older price is refused (409) instead of answered.",
        "parameters": [
          {
            "name": "amount",
            "in": "query",
            "schema": {
              "type": "number",
              "exclusiveMinimum": 0,
              "default": 1
            },
            "example": 100
          },
          {
            "name": "from",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "USD",
            "description": "Asset symbol, case-insensitive (USD, IDR, BTC, ETH, DOT, USDT, TSLA, NVDA, AAPL, AMZN, META, tPOT, pUSD)"
          },
          {
            "name": "to",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "IDR"
          },
          {
            "name": "network",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "portaldot",
                "sepolia"
              ],
              "default": "portaldot"
            }
          },
          {
            "name": "maxAge",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0
            },
            "description": "Refuse if any price used is older than this many seconds"
          }
        ],
        "responses": {
          "200": {
            "description": "Conversion",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Quote"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "502": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "Pair": {
        "name": "pair",
        "in": "query",
        "required": true,
        "schema": {
          "type": "string",
          "enum": [
            "BTC/USD",
            "ETH/USD",
            "DOT/USD",
            "USDT/USD",
            "USD/IDR",
            "EUR/USD",
            "GBP/USD",
            "USD/JPY",
            "USD/CNY",
            "XAU/USD",
            "TSLA/USD",
            "NVDA/USD",
            "AAPL/USD",
            "AMZN/USD",
            "META/USD",
            "tPOT/pUSD"
          ]
        },
        "example": "USD/IDR",
        "description": "Canonical spelling is listed; case-insensitive input with /, - or _ is accepted (usd-idr, BTC_USD) and the response uses the canonical pair."
      }
    },
    "responses": {
      "Error": {
        "description": "Error",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "required": [
                "error"
              ],
              "properties": {
                "error": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "schemas": {
      "Hex32": {
        "type": "string",
        "pattern": "^0x[0-9a-fA-F]{64}$"
      },
      "Address": {
        "type": "string",
        "pattern": "^0x[0-9a-fA-F]{40}$"
      },
      "FeedList": {
        "type": "object",
        "required": [
          "feeds"
        ],
        "properties": {
          "feeds": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "pair",
                "feedId",
                "decimals",
                "heartbeat",
                "deviationBps",
                "maxSpreadBps",
                "sources",
                "aggregators"
              ],
              "properties": {
                "pair": {
                  "type": "string"
                },
                "feedId": {
                  "$ref": "#/components/schemas/Hex32",
                  "description": "keccak256(pair)"
                },
                "description": {
                  "type": "string"
                },
                "decimals": {
                  "type": "integer"
                },
                "heartbeat": {
                  "type": "integer",
                  "description": "seconds"
                },
                "deviationBps": {
                  "type": "integer"
                },
                "maxSpreadBps": {
                  "type": "integer"
                },
                "sources": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "aggregators": {
                  "type": "object",
                  "additionalProperties": {
                    "oneOf": [
                      {
                        "$ref": "#/components/schemas/Address"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                }
              }
            }
          }
        }
      },
      "Bundle": {
        "type": "object",
        "required": [
          "pair",
          "feedId",
          "decimals",
          "roundId",
          "answer",
          "sources",
          "reporters",
          "observations",
          "payload"
        ],
        "properties": {
          "pair": {
            "type": "string"
          },
          "feedId": {
            "$ref": "#/components/schemas/Hex32"
          },
          "decimals": {
            "type": "integer"
          },
          "roundId": {
            "type": "string",
            "description": "uint80 as decimal string"
          },
          "answer": {
            "type": "string",
            "description": "median, scaled by 10^decimals"
          },
          "sources": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "source": {
                  "type": "string"
                },
                "price": {
                  "type": "number"
                }
              }
            }
          },
          "reporters": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Address"
            }
          },
          "observations": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "reporter",
                "roundId",
                "answer",
                "observedAt",
                "r",
                "s",
                "v"
              ],
              "properties": {
                "reporter": {
                  "$ref": "#/components/schemas/Address"
                },
                "roundId": {
                  "type": "string"
                },
                "answer": {
                  "type": "string"
                },
                "observedAt": {
                  "type": "string",
                  "description": "unix seconds"
                },
                "r": {
                  "$ref": "#/components/schemas/Hex32"
                },
                "s": {
                  "$ref": "#/components/schemas/Hex32"
                },
                "v": {
                  "type": "integer"
                }
              }
            }
          },
          "payload": {
            "type": "string",
            "description": "ABI-encoded fulfillOracleQuery argument"
          }
        }
      },
      "Health": {
        "type": "object",
        "required": [
          "ok",
          "checkedAt",
          "networks"
        ],
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "checkedAt": {
            "type": "string",
            "format": "date-time"
          },
          "networks": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "chain",
                "oracle",
                "feeds"
              ],
              "properties": {
                "chain": {
                  "type": "string"
                },
                "oracle": {
                  "$ref": "#/components/schemas/Address"
                },
                "feeds": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "required": [
                      "pair",
                      "status"
                    ],
                    "properties": {
                      "pair": {
                        "type": "string"
                      },
                      "roundId": {
                        "type": "string"
                      },
                      "answer": {
                        "type": "string"
                      },
                      "ageSeconds": {
                        "type": [
                          "integer",
                          "null"
                        ]
                      },
                      "status": {
                        "type": "string",
                        "enum": [
                          "ok",
                          "stale",
                          "no data",
                          "unreadable",
                          "not configured"
                        ]
                      },
                      "error": {
                        "type": "string",
                        "description": "present when status is unreadable"
                      }
                    }
                  }
                },
                "relay": {
                  "type": "object",
                  "description": "The transmitter that pays relay gas (it holds no rights). On Portaldot its tPOT is the feeds' runway; refill instructions in the README.",
                  "required": [
                    "transmitter",
                    "balance"
                  ],
                  "properties": {
                    "transmitter": {
                      "$ref": "#/components/schemas/Address"
                    },
                    "balance": {
                      "type": [
                        "number",
                        "null"
                      ],
                      "description": "native balance (tPOT or ETH)"
                    },
                    "runwayHours": {
                      "type": "integer",
                      "description": "Portaldot only: hours of rounds left at the measured ~0.5 tPOT/h"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "SubstrateRead": {
        "type": "object",
        "required": [
          "network",
          "via",
          "node",
          "oracle",
          "block",
          "blockHash",
          "feeds"
        ],
        "properties": {
          "network": {
            "type": "string"
          },
          "via": {
            "type": "string"
          },
          "node": {
            "type": "string"
          },
          "oracle": {
            "$ref": "#/components/schemas/Address"
          },
          "block": {
            "type": "integer"
          },
          "blockHash": {
            "$ref": "#/components/schemas/Hex32"
          },
          "feeds": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "pair",
                "roundId",
                "answer",
                "updatedAt"
              ],
              "properties": {
                "pair": {
                  "type": "string"
                },
                "roundId": {
                  "type": "string"
                },
                "answer": {
                  "type": "string"
                },
                "updatedAt": {
                  "type": "string",
                  "format": "date-time"
                }
              }
            }
          },
          "notConfigured": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Feeds in feeds.ts this oracle's owner has not configured yet (the read reverts UnknownFeed)"
          }
        }
      },
      "History": {
        "type": "object",
        "required": [
          "net",
          "pair",
          "oracle",
          "fromBlock",
          "toBlock",
          "total",
          "rounds"
        ],
        "properties": {
          "net": {
            "type": "string"
          },
          "pair": {
            "type": "string"
          },
          "oracle": {
            "$ref": "#/components/schemas/Address"
          },
          "fromBlock": {
            "type": "integer"
          },
          "toBlock": {
            "type": "integer"
          },
          "total": {
            "type": "integer"
          },
          "rounds": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "roundId",
                "answer",
                "observedAt",
                "signers",
                "transmitter",
                "block",
                "tx"
              ],
              "properties": {
                "roundId": {
                  "type": "string"
                },
                "answer": {
                  "type": "string"
                },
                "observedAt": {
                  "type": "string",
                  "format": "date-time"
                },
                "signers": {
                  "type": "integer"
                },
                "transmitter": {
                  "$ref": "#/components/schemas/Address"
                },
                "block": {
                  "type": "integer"
                },
                "tx": {
                  "$ref": "#/components/schemas/Hex32"
                }
              }
            }
          },
          "partial": {
            "type": "boolean",
            "description": "true while older blocks are still being scanned (at most 20 chunks per request)"
          }
        }
      },
      "Quote": {
        "type": "object",
        "required": [
          "amount",
          "from",
          "to",
          "result",
          "rate",
          "network",
          "feedsUsed"
        ],
        "properties": {
          "amount": {
            "type": "number"
          },
          "from": {
            "type": "string"
          },
          "to": {
            "type": "string"
          },
          "result": {
            "type": "number"
          },
          "rate": {
            "type": "number"
          },
          "network": {
            "type": "string",
            "enum": [
              "portaldot",
              "sepolia"
            ]
          },
          "feedsUsed": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "pair",
                "price",
                "roundId",
                "ageSeconds",
                "stale"
              ],
              "properties": {
                "pair": {
                  "type": "string"
                },
                "price": {
                  "type": "number"
                },
                "roundId": {
                  "type": "string"
                },
                "ageSeconds": {
                  "type": "integer"
                },
                "stale": {
                  "type": "boolean"
                }
              }
            }
          }
        }
      }
    }
  },
  "security": []
}
