CoinGecko API多链钱包余额交易P&L追踪实战
管理数字资产钱包时,光看当前持仓往往不够——你想知道这段时间做了哪些操作、整体是赚是亏、资产在各条链上是怎么分布的。CoinGecko API提供了一套多链统一的数据接口,用一个provider就能拿到某个地址的余额、交易历史、转账记录以及已实现和未实现的盈亏数据,覆盖超过250条链。这篇就来说说具体怎么调这几个接口。
钱包余额接口能查什么?
Token Balances by Wallet Address这个接口接受一个逗号分隔的链名称列表,比如eth,base,arbitrum,一次请求就能返回目标地址在所有这些链上的代币持仓情况。每个持仓项里自带price_usd和value_usd,不需要再接额外的价格接口。
可以用token_type过滤原生币和ERC-20/SPL代币,用value_usd_min或reserve_in_usd_min过滤dust和低流动性垃圾Token。返回的顶层networks数组会给出每条链的美元总价值和持仓数量,方便你先看整体分布再深入具体余额。
调试时可以用curl直接请求,确认返回数据结构后再集成到自己的项目里。
交易历史怎么拉?
Trades by Wallet Address接口按网络和钱包地址返回交易记录,每条记录标注了buy还是sell,并附带双方Swap的USD价格和总成交量volume_in_usd。支持的网络超过250个,包括以太坊(network="eth")和Solana(network="solana")。
通过from和to参数可以指定最多30天的时间窗口,不传这两个参数默认拉最近7天。如果返回结果太多,响应里的meta会带有next_cursor,传进下一次请求即可翻页。
需要注意的是,一次Swap在这个接口里会生成一条trade记录,对应的Token转入转出会另外出现在转账记录里,两者要合并来看才能还原完整操作。
转账记录有什么用?
Token Transfers by Wallet Address接口返回指定网络上某个地址的Token转账历史。每条记录包含转账方向(in表示转入,out表示转出)、对应的代币数量,以及该Token当时的价格信息。
这个接口的价值在于捕捉那些不走Swap的操作——比如充值、提币、空投等,单纯查交易记录是看不到这些的。direction参数可以只筛选in或out,from和to同样用于时间范围过滤,翻页逻辑和交易接口一致。
盈亏数据怎么算?
PnL by Wallet Address接口返回一个地址在多条链上的已实现和未实现盈亏汇总。它的多链设计逻辑和余额接口一样——传一个逗号分隔的链列表,一次拿全量结果,不需要逐链请求再手动合并。
需要注意的是,查询的多条链必须属于同一个VM家族。比如eth、base、arbitrum可以一起查,因为都是EVM链;Solana就要单独发一次请求。返回内容里既有全链汇总的total_realized_pnl_usd和total_unrealized_pnl_usd,也有按链拆分的networks数组和按Token拆分的token_stats数组。
怎么把四个接口串成完整的多链仪表盘?
余额、交易、转账、盈亏各自提供的是不同的视角,把这四组数据拉到同一个地址下,就能拼出一个完整的链上资产视图。
具体做法是:交易接口和转账接口都按网络分别调用,要把每个网络的Trade和Transfer都拉到同一份列表里,按时间戳排序,用每条记录里的type字段区分是trade还是transfer。同一笔Swap会同时出现一条trade记录和两条transfer记录,合并时要注意去重。
盈亏数据独立于活动流——交易和转账是带时间戳的单个事件,而已实现和未实现盈亏是汇总值,所以get_pnl返回的是单独的PnL摘要,不需要塞进活动流里。
把上述数据渲染到前端,就能做出一个支持多链切换、显示各链资产分布、活动流水和分链盈亏明细的仪表盘。
结语:全链路数据一个provider搞定
CoinGecko的这套Onchain Wallet接口用同一个API provider覆盖了余额、交易历史、Token转账和跨链盈亏四大数据维度,所有返回值自带USD定价,不需要额外对接价格源。查询多条链时一次请求搞定合并,Trade和Transfer合并后形成完整活动时间线,PnL单独拎出来做绩效汇总。
想自己动手试一下,CoinGecko API的Analyst计划解锁了本篇用到的全部四个接口,每月500K调用额度,速率上限500 RPM。还没打算付费的话,也可以先申请免费Demo Key,60多个接口随便玩,每月10K额度够跑几个小项目了。
本文基于公开媒体报道整理,仅作信息参考,不构成任何投资依据,内容以原文为准。