{
  "openapi": "3.1.0",
  "info": {
    "title": "EconDash Economic Data API",
    "version": "1.0.0",
    "description": "Macroeconomic indicators and time series data via x402 and MPP payments. 753 indicators across 298 countries, including GDP, inflation, employment, trade, and more."
  },
  "x-agentcash-guidance": {
    "llmsTxtUrl": "https://econdash.org/llms.txt"
  },
  "servers": [
    { "url": "https://econdash.org/api/v1/m2m" }
  ],
  "paths": {
    "/indicators": {
      "get": {
        "operationId": "listIndicators",
        "summary": "List all economic indicators",
        "description": "Returns the full catalog of available economic indicators with codes, names, categories, units, and source information.",
        "security": [],
        "x-payment-info": {
          "price": { "mode": "fixed", "currency": "USD", "amount": "0.02" },
          "protocols": [{ "x402": { "network": "eip155:8453", "asset": "USDC" } }, { "mpp": { "method": "solana", "intent": "charge", "currency": "USDC" } }, { "mpp": { "method": "tempo", "intent": "charge", "currency": "pathUSD" } }]
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "Array of indicator objects with code, name, category, unit, frequency, and source fields.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "code": { "type": "string", "example": "NY.GDP.MKTP.CD" },
                      "name": { "type": "string", "example": "GDP (current US$)" },
                      "category": { "type": "string", "example": "Economic Growth" },
                      "unit": { "type": "string", "example": "USD" },
                      "frequency": { "type": "string", "example": "yearly" },
                      "source": { "type": "string", "example": "World Bank" }
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "Payment required. Returns x402 and MPP payment challenges in WWW-Authenticate headers."
          }
        }
      }
    },
    "/indicators/by-slug/{slug}": {
      "get": {
        "operationId": "getIndicatorBySlug",
        "summary": "Get indicator metadata by URL slug",
        "description": "Returns detailed metadata for an indicator looked up by its URL-friendly slug (e.g. gdp-current-us).",
        "security": [],
        "x-payment-info": {
          "price": { "mode": "fixed", "currency": "USD", "amount": "0.02" },
          "protocols": [{ "x402": { "network": "eip155:8453", "asset": "USDC" } }, { "mpp": { "method": "solana", "intent": "charge", "currency": "USDC" } }, { "mpp": { "method": "tempo", "intent": "charge", "currency": "pathUSD" } }]
        },
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "description": "URL slug, e.g. gdp-current-us"
          }
        ],
        "responses": {
          "200": {
            "description": "Indicator metadata object.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": { "type": "string" },
                    "name": { "type": "string" },
                    "description": { "type": "string" },
                    "category": { "type": "string" },
                    "unit": { "type": "string" },
                    "frequency": { "type": "string" },
                    "source": { "type": "string" }
                  }
                }
              }
            }
          },
          "402": {
            "description": "Payment required."
          }
        }
      }
    },
    "/indicators/{code}/countries": {
      "get": {
        "operationId": "getIndicatorCountries",
        "summary": "List countries with data for an indicator",
        "description": "Returns the list of countries that have time series data available for a given indicator.",
        "security": [],
        "x-payment-info": {
          "price": { "mode": "fixed", "currency": "USD", "amount": "0.02" },
          "protocols": [{ "x402": { "network": "eip155:8453", "asset": "USDC" } }, { "mpp": { "method": "solana", "intent": "charge", "currency": "USDC" } }, { "mpp": { "method": "tempo", "intent": "charge", "currency": "pathUSD" } }]
        },
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "description": "Indicator code, e.g. NY.GDP.MKTP.CD"
          }
        ],
        "responses": {
          "200": {
            "description": "Array of country objects with iso3, name, and region.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "iso3": { "type": "string", "example": "USA" },
                      "name": { "type": "string", "example": "United States" },
                      "region": { "type": "string", "example": "North America" }
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "Payment required."
          }
        }
      }
    },
    "/indicators/{code}": {
      "get": {
        "operationId": "getIndicator",
        "summary": "Get indicator metadata by code",
        "description": "Returns detailed metadata for a single economic indicator including its full name, description, unit, frequency, category, and source.",
        "security": [],
        "x-payment-info": {
          "price": { "mode": "fixed", "currency": "USD", "amount": "0.02" },
          "protocols": [{ "x402": { "network": "eip155:8453", "asset": "USDC" } }, { "mpp": { "method": "solana", "intent": "charge", "currency": "USDC" } }, { "mpp": { "method": "tempo", "intent": "charge", "currency": "pathUSD" } }]
        },
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "description": "Indicator code, e.g. NY.GDP.MKTP.CD for GDP"
          }
        ],
        "responses": {
          "200": {
            "description": "Indicator metadata object.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": { "type": "string" },
                    "name": { "type": "string" },
                    "description": { "type": "string" },
                    "category": { "type": "string" },
                    "unit": { "type": "string" },
                    "frequency": { "type": "string" },
                    "source": { "type": "string" }
                  }
                }
              }
            }
          },
          "402": {
            "description": "Payment required."
          }
        }
      }
    },
    "/timeseries/{code}/top-countries": {
      "get": {
        "operationId": "getTimeseriesTopCountries",
        "summary": "Get top countries by latest value for an indicator",
        "description": "Returns the top N countries ranked by the most recent value of a given indicator.",
        "security": [],
        "x-payment-info": {
          "price": { "mode": "fixed", "currency": "USD", "amount": "0.02" },
          "protocols": [{ "x402": { "network": "eip155:8453", "asset": "USDC" } }, { "mpp": { "method": "solana", "intent": "charge", "currency": "USDC" } }, { "mpp": { "method": "tempo", "intent": "charge", "currency": "pathUSD" } }]
        },
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "description": "Indicator code, e.g. NY.GDP.MKTP.CD"
          },
          {
            "name": "n",
            "in": "query",
            "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 },
            "description": "Number of top countries to return"
          }
        ],
        "responses": {
          "200": {
            "description": "Array of country objects with latest values, ordered descending.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "iso3": { "type": "string" },
                      "name": { "type": "string" },
                      "value": { "type": "number" },
                      "date": { "type": "string", "format": "date" }
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "Payment required."
          }
        }
      }
    },
    "/timeseries/{code}": {
      "get": {
        "operationId": "getTimeseries",
        "summary": "Get time series data for an indicator",
        "description": "Returns time series data points for a given indicator, optionally filtered by country and date range.",
        "security": [],
        "x-payment-info": {
          "price": { "mode": "fixed", "currency": "USD", "amount": "0.02" },
          "protocols": [{ "x402": { "network": "eip155:8453", "asset": "USDC" } }, { "mpp": { "method": "solana", "intent": "charge", "currency": "USDC" } }, { "mpp": { "method": "tempo", "intent": "charge", "currency": "pathUSD" } }]
        },
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "description": "Indicator code, e.g. FP.CPI.TOTL.ZG for inflation"
          },
          {
            "name": "country",
            "in": "query",
            "schema": { "type": "string" },
            "description": "ISO 3166-1 alpha-3 country code, e.g. USA, DEU, JPN"
          },
          {
            "name": "from",
            "in": "query",
            "schema": { "type": "string", "format": "date" },
            "description": "Start date in YYYY-MM-DD format"
          },
          {
            "name": "to",
            "in": "query",
            "schema": { "type": "string", "format": "date" },
            "description": "End date in YYYY-MM-DD format"
          }
        ],
        "responses": {
          "200": {
            "description": "Time series data points with date and value fields.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "date": { "type": "string", "format": "date" },
                      "value": { "type": "number" },
                      "country": { "type": "string" },
                      "indicator": { "type": "string" }
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "Payment required."
          }
        }
      }
    },
    "/countries": {
      "get": {
        "operationId": "listCountries",
        "summary": "List all available countries",
        "description": "Returns a list of all countries and regions with available economic data.",
        "security": [],
        "x-payment-info": {
          "price": { "mode": "fixed", "currency": "USD", "amount": "0.02" },
          "protocols": [{ "x402": { "network": "eip155:8453", "asset": "USDC" } }, { "mpp": { "method": "solana", "intent": "charge", "currency": "USDC" } }, { "mpp": { "method": "tempo", "intent": "charge", "currency": "pathUSD" } }]
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "Array of country objects with iso3, name, and region fields.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "iso3": { "type": "string", "example": "USA" },
                      "name": { "type": "string", "example": "United States" },
                      "region": { "type": "string", "example": "North America" }
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "Payment required."
          }
        }
      }
    },
    "/countries/{iso3}/indicators": {
      "get": {
        "operationId": "getCountryIndicators",
        "summary": "List indicators available for a country",
        "description": "Returns all economic indicators and their latest values for a specific country.",
        "security": [],
        "x-payment-info": {
          "price": { "mode": "fixed", "currency": "USD", "amount": "0.02" },
          "protocols": [{ "x402": { "network": "eip155:8453", "asset": "USDC" } }, { "mpp": { "method": "solana", "intent": "charge", "currency": "USDC" } }, { "mpp": { "method": "tempo", "intent": "charge", "currency": "pathUSD" } }]
        },
        "parameters": [
          {
            "name": "iso3",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "description": "ISO 3166-1 alpha-3 code, e.g. DEU"
          }
        ],
        "responses": {
          "200": {
            "description": "Array of indicator objects with latest values for the country.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "code": { "type": "string" },
                      "name": { "type": "string" },
                      "latestValue": { "type": "number" },
                      "latestDate": { "type": "string", "format": "date" }
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "Payment required."
          }
        }
      }
    },
    "/countries/{iso3}": {
      "get": {
        "operationId": "getCountry",
        "summary": "Get country economic profile",
        "description": "Returns metadata for a country including region and list of available indicators.",
        "security": [],
        "x-payment-info": {
          "price": { "mode": "fixed", "currency": "USD", "amount": "0.02" },
          "protocols": [{ "x402": { "network": "eip155:8453", "asset": "USDC" } }, { "mpp": { "method": "solana", "intent": "charge", "currency": "USDC" } }, { "mpp": { "method": "tempo", "intent": "charge", "currency": "pathUSD" } }]
        },
        "parameters": [
          {
            "name": "iso3",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "description": "ISO 3166-1 alpha-3 country code, e.g. DEU, CHN, BRA"
          }
        ],
        "responses": {
          "200": {
            "description": "Country profile with metadata and indicator list.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "iso3": { "type": "string" },
                    "name": { "type": "string" },
                    "region": { "type": "string" },
                    "indicators": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "code": { "type": "string" },
                          "name": { "type": "string" },
                          "latestValue": { "type": "number" },
                          "latestDate": { "type": "string" }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "Payment required."
          }
        }
      }
    },
    "/categories": {
      "get": {
        "operationId": "listCategories",
        "summary": "List all indicator categories",
        "description": "Returns the list of indicator categories used to organize the economic data catalog.",
        "security": [],
        "x-payment-info": {
          "price": { "mode": "fixed", "currency": "USD", "amount": "0.02" },
          "protocols": [{ "x402": { "network": "eip155:8453", "asset": "USDC" } }, { "mpp": { "method": "solana", "intent": "charge", "currency": "USDC" } }, { "mpp": { "method": "tempo", "intent": "charge", "currency": "pathUSD" } }]
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "Array of category objects with name and indicator count.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "name": { "type": "string", "example": "Economic Growth" },
                      "indicatorCount": { "type": "integer", "example": 42 }
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "Payment required."
          }
        }
      }
    },
    "/news": {
      "get": {
        "operationId": "listNews",
        "summary": "List economic news articles",
        "description": "Returns a list of economic news articles, optionally filtered by indicator or country.",
        "security": [],
        "x-payment-info": {
          "price": { "mode": "fixed", "currency": "USD", "amount": "0.02" },
          "protocols": [{ "x402": { "network": "eip155:8453", "asset": "USDC" } }, { "mpp": { "method": "solana", "intent": "charge", "currency": "USDC" } }, { "mpp": { "method": "tempo", "intent": "charge", "currency": "pathUSD" } }]
        },
        "parameters": [
          {
            "name": "indicator",
            "in": "query",
            "schema": { "type": "string" },
            "description": "Filter by indicator code, e.g. NY.GDP.MKTP.CD"
          },
          {
            "name": "country",
            "in": "query",
            "schema": { "type": "string" },
            "description": "Filter by ISO3 country code, e.g. USA"
          }
        ],
        "responses": {
          "200": {
            "description": "Array of news article summaries.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": { "type": "integer" },
                      "title": { "type": "string" },
                      "publishedAt": { "type": "string", "format": "date-time" },
                      "source": { "type": "string" },
                      "url": { "type": "string" }
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "Payment required."
          }
        }
      }
    },
    "/news/{news_id}": {
      "get": {
        "operationId": "getNewsItem",
        "summary": "Get a single news article by ID",
        "description": "Returns the full content of a specific economic news article.",
        "security": [],
        "x-payment-info": {
          "price": { "mode": "fixed", "currency": "USD", "amount": "0.02" },
          "protocols": [{ "x402": { "network": "eip155:8453", "asset": "USDC" } }, { "mpp": { "method": "solana", "intent": "charge", "currency": "USDC" } }, { "mpp": { "method": "tempo", "intent": "charge", "currency": "pathUSD" } }]
        },
        "parameters": [
          {
            "name": "news_id",
            "in": "path",
            "required": true,
            "schema": { "type": "integer" },
            "description": "News item ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Full news article with content.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": { "type": "integer" },
                    "title": { "type": "string" },
                    "content": { "type": "string" },
                    "publishedAt": { "type": "string", "format": "date-time" },
                    "source": { "type": "string" },
                    "url": { "type": "string" }
                  }
                }
              }
            }
          },
          "402": {
            "description": "Payment required."
          }
        }
      }
    },
    "/sources": {
      "get": {
        "operationId": "listSources",
        "summary": "List all data sources",
        "description": "Returns a list of all data sources used for economic indicators.",
        "security": [],
        "x-payment-info": {
          "price": { "mode": "fixed", "currency": "USD", "amount": "0.02" },
          "protocols": [{ "x402": { "network": "eip155:8453", "asset": "USDC" } }, { "mpp": { "method": "solana", "intent": "charge", "currency": "USDC" } }, { "mpp": { "method": "tempo", "intent": "charge", "currency": "pathUSD" } }]
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "Array of data source objects.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": { "type": "integer" },
                      "name": { "type": "string", "example": "World Bank" },
                      "description": { "type": "string" }
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "Payment required."
          }
        }
      }
    },
    "/news-sources": {
      "get": {
        "operationId": "listNewsSources",
        "summary": "List news sources",
        "description": "Returns a list of news outlets and sources tracked by EconDash.",
        "security": [],
        "x-payment-info": {
          "price": { "mode": "fixed", "currency": "USD", "amount": "0.02" },
          "protocols": [{ "x402": { "network": "eip155:8453", "asset": "USDC" } }, { "mpp": { "method": "solana", "intent": "charge", "currency": "USDC" } }, { "mpp": { "method": "tempo", "intent": "charge", "currency": "pathUSD" } }]
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "Array of news source objects.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": { "type": "integer" },
                      "name": { "type": "string", "example": "Reuters" },
                      "url": { "type": "string" }
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "Payment required."
          }
        }
      }
    },
    "/stats": {
      "get": {
        "operationId": "getStats",
        "summary": "Get database statistics",
        "description": "Returns summary statistics about the database: total indicators, countries, data points, and last update timestamps.",
        "security": [],
        "x-payment-info": {
          "price": { "mode": "fixed", "currency": "USD", "amount": "0.02" },
          "protocols": [{ "x402": { "network": "eip155:8453", "asset": "USDC" } }, { "mpp": { "method": "solana", "intent": "charge", "currency": "USDC" } }, { "mpp": { "method": "tempo", "intent": "charge", "currency": "pathUSD" } }]
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "Database statistics object.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "totalIndicators": { "type": "integer" },
                    "totalCountries": { "type": "integer" },
                    "totalDataPoints": { "type": "integer" },
                    "lastSync": { "type": "string" },
                    "lastFetch": { "type": "string" }
                  }
                }
              }
            }
          },
          "402": {
            "description": "Payment required."
          }
        }
      }
    }
  }
}