From 4855ce374e1591f7caabc6d6f170f5c15cf37073 Mon Sep 17 00:00:00 2001
From: shaneauerbach <shaneauerbach@gmail.com>
Date: Fri, 16 Jan 2026 08:42:37 -0800
Subject: [PATCH] Add warnings field to token-info, collectibles, and
 defi-positions endpoints

Extends the unsupported chain ID warnings (introduced in #136 for balances)
to the remaining EVM endpoints. When users request data for unsupported
chain IDs, the API now returns a warnings array with:
- code: UNSUPPORTED_CHAIN_IDS
- message: Human-readable description
- chain_ids: List of unsupported chain IDs
- docs_url: Link to supported chains documentation

This provides consistent behavior across all EVM endpoints.
---
 evm/openapi/collectibles.json   | 39 +++++++++++++++++++++++++++++++++
 evm/openapi/defi-positions.json | 39 +++++++++++++++++++++++++++++++++
 evm/openapi/token-info.json     | 39 +++++++++++++++++++++++++++++++++
 3 files changed, 117 insertions(+)

diff --git a/evm/openapi/collectibles.json b/evm/openapi/collectibles.json
index d76995a..3f5bdc0 100644
--- a/evm/openapi/collectibles.json
+++ b/evm/openapi/collectibles.json
@@ -182,6 +182,38 @@
           "is_spam"
         ]
       },
+      "Warning": {
+        "type": "object",
+        "required": [
+          "code",
+          "message"
+        ],
+        "properties": {
+          "code": {
+            "type": "string",
+            "description": "Warning code identifier",
+            "example": "UNSUPPORTED_CHAIN_IDS"
+          },
+          "message": {
+            "type": "string",
+            "description": "Human-readable warning message",
+            "example": "Some chain_ids are not supported."
+          },
+          "chain_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "List of chain IDs that triggered this warning (for chain-related warnings)"
+          },
+          "docs_url": {
+            "type": "string",
+            "description": "URL to documentation with more information about the warning",
+            "example": "https://docs.sim.dune.com/evm/supported-chains"
+          }
+        }
+      },
       "CollectiblesResponse": {
         "type": "object",
         "properties": {
@@ -197,6 +229,13 @@
             },
             "description": "A list of collectible entries."
           },
+          "warnings": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/Warning"
+            },
+            "description": "Array of warnings that occurred during request processing. Warnings indicate non-fatal issues (e.g., unsupported chain IDs) where the request can still be partially fulfilled."
+          },
           "next_offset": {
             "type": "string",
             "description": "Use this value as the `offset` in your next request to continue pagination. Not included when there are no more entries."
diff --git a/evm/openapi/defi-positions.json b/evm/openapi/defi-positions.json
index 5e63b59..f7a83d4 100644
--- a/evm/openapi/defi-positions.json
+++ b/evm/openapi/defi-positions.json
@@ -1103,6 +1103,38 @@
           }
         }
       },
+      "Warning": {
+        "type": "object",
+        "required": [
+          "code",
+          "message"
+        ],
+        "properties": {
+          "code": {
+            "type": "string",
+            "description": "Warning code identifier",
+            "example": "UNSUPPORTED_CHAIN_IDS"
+          },
+          "message": {
+            "type": "string",
+            "description": "Human-readable warning message",
+            "example": "Some chain_ids are not supported."
+          },
+          "chain_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "List of chain IDs that triggered this warning (for chain-related warnings)"
+          },
+          "docs_url": {
+            "type": "string",
+            "description": "URL to documentation with more information about the warning",
+            "example": "https://docs.sim.dune.com/evm/supported-chains"
+          }
+        }
+      },
       "DefiPositionsResponse": {
         "type": "object",
         "required": ["positions"],
@@ -1119,6 +1151,13 @@
                 "$ref": "#/components/schemas/DefiAggregations"
               }
             ]
+          },
+          "warnings": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/Warning"
+            },
+            "description": "Array of warnings that occurred during request processing. Warnings indicate non-fatal issues (e.g., unsupported chain IDs) where the request can still be partially fulfilled."
           }
         }
       }
diff --git a/evm/openapi/token-info.json b/evm/openapi/token-info.json
index 78795e6..6a0aff6 100644
--- a/evm/openapi/token-info.json
+++ b/evm/openapi/token-info.json
@@ -200,6 +200,38 @@
           }
         }
       },
+      "Warning": {
+        "type": "object",
+        "required": [
+          "code",
+          "message"
+        ],
+        "properties": {
+          "code": {
+            "type": "string",
+            "description": "Warning code identifier",
+            "example": "UNSUPPORTED_CHAIN_IDS"
+          },
+          "message": {
+            "type": "string",
+            "description": "Human-readable warning message",
+            "example": "Some chain_ids are not supported."
+          },
+          "chain_ids": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "format": "int64"
+            },
+            "description": "List of chain IDs that triggered this warning (for chain-related warnings)"
+          },
+          "docs_url": {
+            "type": "string",
+            "description": "URL to documentation with more information about the warning",
+            "example": "https://docs.sim.dune.com/evm/supported-chains"
+          }
+        }
+      },
       "TokensResponse": {
         "type": "object",
         "required": [
@@ -218,6 +250,13 @@
             },
             "description": "Array of token information across different chains"
           },
+          "warnings": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/Warning"
+            },
+            "description": "Array of warnings that occurred during request processing. Warnings indicate non-fatal issues (e.g., unsupported chain IDs) where the request can still be partially fulfilled."
+          },
           "next_offset": {
             "type": "string",
             "description": "Pagination cursor for the next page of results"