feat: add JSON:API content negotiation support for REST endpoints

README.md

@@ -440,6 +440,99 @@ If `HORIZON_URL` is set, the indexer checks the RPC source first and switches to
 
 ***
 
+## JSON:API Content Negotiation
+
+All `GET` endpoints support the JSON:API specification via content negotiation. Include an `Accept: application/vnd.api+json` header to receive responses in JSON:API format.
+
+### JSON:API Response Structure
+
+Responses are transformed to the JSON:API document structure:
+
+- **Collection endpoints** return an array in the `data` member with pagination metadata in `meta`
+- **Single resource endpoints** return a single resource object in `data`
+- **Error responses** return an array in the `errors` member with `title` and `detail` fields
+- **Dates** are serialized as ISO 8601 strings
+- **BigInt values** are converted to strings
+
+### Example: Transfers in JSON:API Format
+
+```bash
+# Request with JSON:API Accept header
+curl -H "Accept: application/vnd.api+json" http://localhost:3000/transfers/address/GABC123...
+
+# Response
+{
+  "data": [
+    {
+      "id": "evt-001",
+      "type": "transfer",
+      "attributes": {
+        "contractId": "CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD2KM",
+        "eventType": "transfer",
+        "fromAddress": "GBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBWWHF",
+        "toAddress": "GAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAWHF",
+        "amount": "10000000",
+        "ledger": 1001,
+        "ledgerClosedAt": "2025-01-01T00:00:00.000Z",
+        "txHash": "aaaa1111",
+        "displayAmount": "1.0000000"
+      }
+    }
+  ],
+  "meta": {
+    "total": 1,
+    "limit": 50,
+    "offset": 0
+  }
+}
+```
+
+### Example: Summary in JSON:API Format
+
+```bash
+curl -H "Accept: application/vnd.api+json" http://localhost:3000/summary/GABC123...
+
+{
+  "data": [
+    {
+      "id": "CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD2KM",
+      "type": "token-summary",
+      "attributes": {
+        "contractId": "CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD2KM",
+        "totalReceived": "110000000",
+        "totalSent": "170000000",
+        "netFlow": "-60000000",
+        "txCount": 3
+      }
+    }
+  ],
+  "meta": {
+    "address": "GAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAWHF",
+    "window": { "fromDate": null, "toDate": null }
+  }
+}
+```
+
+### Supported Endpoints
+
+| Endpoint | Resource Type |
+|----------|---------------|
+| `GET /transfers/address/:address` | `transfer` |
+| `GET /transfers/incoming/:address` | `transfer` |
+| `GET /transfers/outgoing/:address` | `transfer` |
+| `GET /transfers/tx/:txHash` | `transfer` |
+| `GET /summary/:address` | `token-summary` |
+| `GET /accounts/:address/summary` | `account-summary` |
+| `GET /accounts/:address/transfers` | `transfer` |
+| `GET /assets/popular` | `popular-asset` |
+| `GET /nfts/transfers` | `nft-transfer` |
+| `GET /nfts/owners/:contract/:token_id` | `nft-owner` |
+| `GET /status` | `status` |
+| `GET /healthz` | `health` |
+| `GET /readyz` | `readiness` |
+
+***
+
 ## Event Types Indexed
 
 | Type       | `fromAddress` | `toAddress` | Context                         |

clients/react-query/src/schema.d.ts

@@ -1831,6 +1831,87 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/search": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Fuzzy search across accounts, assets, and contracts */
+        get: {
+            parameters: {
+                query: {
+                    q: string;
+                };
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description OK */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            query: string;
+                            count: number;
+                            results: {
+                                /** @enum {string} */
+                                type: "account" | "asset" | "contract";
+                                value: string;
+                                isSac?: boolean;
+                                lastActivityAt?: string;
+                            }[];
+                        };
+                    };
+                };
+                /** @description Bad Request */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            error: string;
+                        };
+                    };
+                };
+                /** @description Not Found */
+                404: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            error: string;
+                        };
+                    };
+                };
+                /** @description Internal Server Error */
+                500: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            error: string;
+                        };
+                    };
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
 }
 export type webhooks = Record<string, never>;
 export interface components {

openapi.json

@@ -3721,6 +3721,131 @@
           }
         }
       }
+    },
+    "/search": {
+      "get": {
+        "summary": "Fuzzy search across accounts, assets, and contracts",
+        "parameters": [
+          {
+            "schema": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 80
+            },
+            "required": true,
+            "name": "q",
+            "in": "query"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "query": {
+                      "type": "string"
+                    },
+                    "count": {
+                      "type": "integer"
+                    },
+                    "results": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "type": {
+                            "type": "string",
+                            "enum": [
+                              "account",
+                              "asset",
+                              "contract"
+                            ]
+                          },
+                          "value": {
+                            "type": "string"
+                          },
+                          "isSac": {
+                            "type": "boolean"
+                          },
+                          "lastActivityAt": {
+                            "type": "string"
+                          }
+                        },
+                        "required": [
+                          "type",
+                          "value"
+                        ]
+                      }
+                    }
+                  },
+                  "required": [
+                    "query",
+                    "count",
+                    "results"
+                  ]
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad Request",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "error": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "error"
+                  ]
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not Found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "error": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "error"
+                  ]
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Internal Server Error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "error": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "error"
+                  ]
+                }
+              }
+            }
+          }
+        }
+      }
     }
   }
 }