Copy page

Flujos Técnicos

Supply API (CoinGecko)

Overview

Endpoints públicos (sin autenticación) que exponen el total supply y circulating supply de cada token. Diseñados para ser consumidos por agregadores como CoinGecko, CoinMarketCap, etc.

Base path: GET /app/v1/supply/...

Endpoints

Endpoint	Content-Type	Descripción
GET /supply/total/:symbol	text/plain	Total supply de un token (suma de todas las redes)
GET /supply/circulating/:symbol	text/plain	Circulating supply de un token (suma de todas las redes)
GET /supply/detail	application/json	Detalle de todos los tokens con desglose por red
GET /supply/detail/:symbol	application/json	Detalle de un token con desglose por red

El parámetro :symbol es case-insensitive (argt, ARGt, ARGT funcionan igual).

Fórmula

Code
Total Supply       = Σ ERC20.totalSupply() por cada red del token
Circulating Supply = Total Supply - Σ balanceOf(wallet) de wallets no circulantes

Las wallets no circulantes son treasuries, reserves, LP pools, etc. configuradas como CirculationWallet activas en el dashboard.

Flujo

Ejemplos

Total supply (text/plain)

Code
curl https://api.twin.finance/app/v1/supply/total/ARGt
# → 12704796257.97492108

Circulating supply (text/plain)

Code
curl https://api.twin.finance/app/v1/supply/circulating/ARGt
# → 12066772753.16973390

Detalle por token (JSON)

Code
curl https://api.twin.finance/app/v1/supply/detail/ARGt

Code
{
  "data": {
    "symbol": "ARGt",
    "totalSupply": "12704796257.97492108",
    "circulatingSupply": "12066772753.16973390",
    "networks": [
      {
        "network": "BASE",
        "totalSupply": "10000000000.00000000",
        "circulatingSupply": "9500000000.00000000"
      },
      {
        "network": "POLYGON",
        "totalSupply": "2704796257.97492108",
        "circulatingSupply": "2566772753.16973390"
      }
    ]
  }
}

Detalle todos los tokens (JSON)

Code
curl https://api.twin.finance/app/v1/supply/detail

Code
{
  "data": {
    "tokens": [
      {
        "symbol": "ARGt",
        "totalSupply": "12704796257.97492108",
        "circulatingSupply": "12066772753.16973390",
        "networks": [...]
      },
      {
        "symbol": "BRAt",
        "totalSupply": "...",
        "circulatingSupply": "...",
        "networks": [...]
      }
    ]
  }
}

Error: token no encontrado

Code
curl https://api.twin.finance/app/v1/supply/total/INVALID
# → 404 "Token not found"

Configuración de tokens

Para que un token aparezca en los endpoints:

1. OpsToken: Debe existir en Operations > Tokens (dashboard) con un description que empiece con el symbol (ej: "ARGt BASE")
2. CirculationWallet: Al menos 1 wallet activa asociada al token
3. Multi-red: Si el token existe en múltiples redes (ej: ARGt en Base + Polygon), crear un OpsToken por red. El endpoint agrupa automáticamente por symbol y suma los supplies.

Implementación

Archivo	Rol
packages/platform/src/routes/app/v1/supply.ts	Controller — 4 endpoints, cache 5 min
packages/shared/src/service/circulation.service.ts	getSupplyData() — lectura on-chain, agrupación por symbol
packages/platform/src/middleware/auth.ts	/app/v1/supply en PUBLIC_ROUTES

Notas para integradores

• Cache: Datos se refrescan cada 5 minutos. Pollear más frecuente no aporta datos nuevos.
• Formato numérico: 8 decimales fijos (ej: 12704796257.97492108).
• Redes: Base, Polygon, Arbitrum (según configuración de OpsTokens).
• Tokens actuales: ARGt, BRAt, MEXt, COLt, PERt, CHLt, BOLt, USDC.
• CloudFlare WAF: Si hay WAF activo, configurar regla para permitir User-Agent: CoinGecko y X-Requested-With: com.coingecko.