{"id":31067388,"url":"https://github.com/balancer/balancer-v3-dex-screener-api","last_synced_at":"2025-09-15T20:00:05.375Z","repository":{"id":307441785,"uuid":"1029499082","full_name":"balancer/balancer-v3-dex-screener-api","owner":"balancer","description":null,"archived":false,"fork":false,"pushed_at":"2025-08-22T08:04:33.000Z","size":120,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-22T09:43:54.321Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://balancer-v3-dex-screener-adapter-theta.vercel.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/balancer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-31T06:24:16.000Z","updated_at":"2025-08-22T08:04:36.000Z","dependencies_parsed_at":"2025-07-31T10:15:40.936Z","dependency_job_id":"96834185-0e2f-436e-b169-dc18e46a21fa","html_url":"https://github.com/balancer/balancer-v3-dex-screener-api","commit_stats":null,"previous_names":["balancer/balancer-v3-dex-screener-api"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/balancer/balancer-v3-dex-screener-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/balancer%2Fbalancer-v3-dex-screener-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/balancer%2Fbalancer-v3-dex-screener-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/balancer%2Fbalancer-v3-dex-screener-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/balancer%2Fbalancer-v3-dex-screener-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/balancer","download_url":"https://codeload.github.com/balancer/balancer-v3-dex-screener-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/balancer%2Fbalancer-v3-dex-screener-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275312966,"owners_count":25442563,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-15T02:00:09.272Z","response_time":75,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-09-15T20:00:03.205Z","updated_at":"2025-09-15T20:00:05.347Z","avatar_url":"https://github.com/balancer.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Balancer V3 DEX Screener Adapter\n\nA comprehensive multi-chain REST API adapter for Balancer V3 pools, providing DEX Screener compatible endpoints across multiple blockchain networks.\n\n## 📡 API Endpoints\n\n### Base URL\n\n```\nhttp://localhost:3001/api\n```\n\n### Chain Management\n\n-   `GET /api/chains` - List all supported chains\n\n### Universal Endpoints\n\n-   `GET /api/health` - Health check\n\n### Per-Chain Endpoints\n\nAll chain-specific endpoints follow the pattern: `/api/{chain}/...`\n\n| Endpoint                                                | Description        | Example                                        |\n| ------------------------------------------------------- | ------------------ | ---------------------------------------------- |\n| `GET /api/{chain}/latest-block`                         | Latest block info  | `/api/ethereum/latest-block`                   |\n| `GET /api/{chain}/asset?id={address}`                   | Token information  | `/api/arbitrum/asset?id=0x123...`              |\n| `GET /api/{chain}/pair?id={pairId}`                     | Pair information   | `/api/base/pair?id=0xabc...`                   |\n| `GET /api/{chain}/events?fromBlock={from}\u0026toBlock={to}` | Block range events | `/api/base/events?fromBlock=1000\u0026toBlock=2000` |\n\n### API Examples\n\n#### Get Latest Block\n\n```bash\ncurl \"http://localhost:3001/api/ethereum/latest-block\"\n```\n\n```json\n{\n    \"success\": true,\n    \"data\": {\n        \"blockNumber\": 19123456,\n        \"blockTimestamp\": 1752762620\n    },\n    \"timestamp\": 1752762620190\n}\n```\n\n#### Get Asset Information\n\n```bash\ncurl \"http://localhost:3001/api/arbitrum/asset?id=0x82af49447d8a07e3bd95bd0d56f35241523fbab1\"\n```\n\n```json\n{\n    \"success\": true,\n    \"data\": {\n        \"id\": \"0x82af49447d8a07e3bd95bd0d56f35241523fbab1\",\n        \"name\": \"Wrapped Ether\",\n        \"symbol\": \"WETH\",\n        \"decimals\": 18,\n        \"totalSupply\": null,\n        \"maxSupply\": null,\n        \"circulatingSupply\": null,\n        \"info\": {\n            \"address\": \"0x82af49447d8a07e3bd95bd0d56f35241523fbab1\"\n        }\n    },\n    \"timestamp\": 1752762655998\n}\n```\n\n#### Get Events\n\n```bash\ncurl \"http://localhost:3001/api/base/events?fromBlock=50000000\u0026toBlock=50000100\"\n```\n\n```json\n{\n    \"success\": true,\n    \"data\": [\n        {\n            \"block\": {\n                \"blockNumber\": 50000050,\n                \"blockTimestamp\": 1752762610\n            },\n            \"eventType\": \"swap\",\n            \"txnId\": \"0x1234567890abcdef...\",\n            \"txnIndex\": 0,\n            \"eventIndex\": 1,\n            \"maker\": \"0xuser123...\",\n            \"pairId\": \"0xpool...-0xtoken0...-0xtoken1...\",\n            \"priceNative\": \"1.0025\",\n            \"asset0In\": \"1000000000000000000\",\n            \"asset1Out\": \"1002500000000000000\",\n            \"reserves\": {\n                \"asset0\": \"1000000000000000000000\",\n                \"asset1\": \"999000000000000000000\"\n            }\n        }\n    ],\n    \"timestamp\": 1752762633599\n}\n```\n\n## ⚙️ Configuration\n\n### Environment Variables\n\nCreate a `.env` file with the following configuration:\n\n### Environment Variable Pattern\n\nFor each supported chain, you need two environment variables:\n\n-   `SUBGRAPH_URL_{CHAIN}` - The GraphQL subgraph endpoint\n-   `RPC_URL_{CHAIN}` - The JSON-RPC endpoint\n\nWhere `{CHAIN}` is the uppercase chain slug (e.g., `ETHEREUM`, `ARBITRUM`).\n\n## 🛠️ Installation \u0026 Setup\n\n### Prerequisites\n\n-   Node.js 18+ or Bun runtime\n-   TypeScript 5.0+\n-   Access to Balancer V3 subgraphs\n\n### Installation\n\n1. **Clone the repository:**\n\n```bash\ngit clone https://github.com/your-repo/balancer-v3-dex-screener-adapter.git\ncd balancer-v3-dex-screener-adapter\n```\n\n2. **Install dependencies:**\n\n```bash\n# Using npm\nnpm install\n\n# Or using bun\nbun install\n```\n\n3. **Configure environment:**\n\n```bash\ncp .env.example .env\n# Edit .env with your API keys and endpoints\n```\n\n4. **Build the project:**\n\n```bash\nnpm run build\n```\n\n5. **Start the server:**\n\n```bash\n# Development mode\nnpm run dev\n\n# Production mode\nnpm start\n```\n\n### Development Commands\n\n```bash\n# Start development server with hot reload\nnpm run dev\n\n# Build TypeScript\nnpm run build\n\n# Run tests\nnpm test\n\n# Lint code\nnpm run lint\n\n# Test specific chain\ncurl http://localhost:3001/api/ethereum/latest-block\n```\n\n### Testing\n\nThe project includes comprehensive test coverage for all components:\n\n#### Running Tests\n\n```bash\n\n# Run tests in isolation\nbun run test:isolated\n\n# Run specific module test\nbun run test swap-util\n```\n\n**Note**: Due to module mocking conflicts in complex test suites, some tests may fail when run together but pass individually. Use `bun run test:isolated` to run tests in separate processes for guaranteed isolation.\n\n## 🔧 Adding New Chains\n\n### Step 1: Add Environment Variables\n\n```env\nSUBGRAPH_URL_NEWCHAIN=https://your-subgraph-url\nRPC_URL_NEWCHAIN=https://your-rpc-url\n```\n\n### Step 2: Update Chain Configuration\n\n```typescript\n// In src/utils/chain-config.ts\nimport { newchain } from 'viem/chains';\n\n// Add to initializeConfigs()\nconst newchainSubgraphUrl = process.env.SUBGRAPH_URL_NEWCHAIN;\nconst newchainRpcUrl = process.env.RPC_URL_NEWCHAIN;\n\nif (newchainSubgraphUrl \u0026\u0026 newchainRpcUrl) {\n    this.configs.set('newchain', {\n        apiSlug: 'NEWCHAIN',\n        viemChain: newchain,\n        subgraphUrl: newchainSubgraphUrl,\n        rpcUrl: newchainRpcUrl,\n    });\n}\n```\n\n### Step 3: Update GraphQL Client Mapping\n\n```typescript\n// In src/graphql/client.ts\nconst apiSlugToChainSlug: Record\u003cstring, string\u003e = {\n    // ... existing mappings\n    NEWCHAIN: 'newchain',\n};\n```\n\n### Step 4: Test the New Chain\n\n```bash\ncurl http://localhost:3001/api/newchain/latest-block\n```\n\n## 📚 Token Mapping\n\n### ERC4626 Support\n\nThe adapter automatically handles ERC4626 wrapped tokens by:\n\n1. **Querying Balancer API**: Fetches token metadata per chain\n2. **Condition Checking**: Validates `useUnderlyingForAddRemove` and `canUseBufferForSwaps`\n3. **Underlying Resolution**: Maps pool tokens to underlying tokens\n\n### Supported Token Types\n\n-   Standard ERC20 tokens\n-   ERC4626 wrapped tokens (with underlying mapping)\n-   Boosted pool tokens\n-   Native token wrappers (WETH, WMATIC, etc.)\n\n## 🚨 Error Handling\n\n### HTTP Status Codes\n\n-   `200` - Success\n-   `400` - Bad Request (invalid parameters, unsupported chain)\n-   `404` - Not Found (asset/pair not found)\n-   `500` - Internal Server Error\n\n### Error Response Format\n\n```json\n{\n    \"success\": false,\n    \"error\": \"Detailed error message\",\n    \"timestamp\": 1752762677324\n}\n```\n\n### Unsupported Chain Example\n\n```json\n{\n    \"success\": false,\n    \"error\": \"Unsupported chain: xyz. Supported chains: ethereum, arbitrum, optimism, base, avalanche, gnosis, sonic, hyperevm\",\n    \"timestamp\": 1752762677324\n}\n```\n\n## 🚀 Deployment\n\n### Deploy to Vercel\n\nThis application is optimized for serverless deployment on Vercel:\n\n#### One-Click Deploy\n\n[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/your-username/balancer-v3-dex-screener-adapter)\n\n#### Manual Deployment\n\n1. **Fork/Clone this repository**\n\n2. **Install Vercel CLI** (if not already installed):\n\n```bash\nnpm install -g vercel\n```\n\n3. **Login to Vercel**:\n\n```bash\nvercel login\n```\n\n4. **Configure Environment Variables**:\n\n    - Copy `.env.example` to understand required variables\n    - In Vercel Dashboard → Project → Settings → Environment Variables\n    - Add all required chain configuration variables:\n        ```\n        SUBGRAPH_URL_ETHEREUM=https://your-ethereum-subgraph-url\n        RPC_URL_ETHEREUM=https://your-ethereum-rpc-url\n        SUBGRAPH_URL_ARBITRUM=https://your-arbitrum-subgraph-url\n        RPC_URL_ARBITRUM=https://your-arbitrum-rpc-url\n        # ... add other chains as needed\n        ```\n\n5. **Deploy**:\n\n```bash\nvercel --prod\n```\n\n#### Environment Variables for Vercel\n\nRequired environment variables (set in Vercel Dashboard):\n\n| Variable                | Description                | Example                                     |\n| ----------------------- | -------------------------- | ------------------------------------------- |\n| `SUBGRAPH_URL_ETHEREUM` | Ethereum subgraph endpoint | `https://api.studio.thegraph.com/query/...` |\n| `RPC_URL_ETHEREUM`      | Ethereum RPC endpoint      | `https://eth-mainnet.alchemyapi.io/v2/KEY`  |\n| `SUBGRAPH_URL_ARBITRUM` | Arbitrum subgraph endpoint | `https://api.studio.thegraph.com/query/...` |\n| `RPC_URL_ARBITRUM`      | Arbitrum RPC endpoint      | `https://arb-mainnet.g.alchemy.com/v2/KEY`  |\n| ...                     | Additional chains          | ...                                         |\n\n#### Vercel Configuration\n\nThe project includes:\n\n-   `vercel.json` - Vercel deployment configuration\n-   `api/index.ts` - Serverless function entry point\n-   Automatic TypeScript compilation during build\n\n#### Post-Deployment\n\nAfter deployment, your API will be available at:\n\n```\nhttps://your-project.vercel.app/api/health\nhttps://your-project.vercel.app/api/chains\nhttps://your-project.vercel.app/api/{chain}/latest-block\n```\n\n### Local Development vs. Production\n\n-   **Local**: Uses `src/server.ts` with Express server\n-   **Vercel**: Uses `api/index.ts` with serverless functions\n-   Both share the same API routes and business logic\n\n**Built with ❤️ for the Balancer ecosystem**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbalancer%2Fbalancer-v3-dex-screener-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbalancer%2Fbalancer-v3-dex-screener-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbalancer%2Fbalancer-v3-dex-screener-api/lists"}