Duo Data Utilities: IBAN, ISIN, VAT and Tax ID, Barcode, Timezone, Geo APIs

IBAN、ISIN、VAT/税号和 GTIN 条码验证，以及为 AI Agent 提供的另外 29 种实用工具。按次付费（通过 x402 在 Base 上支付 $0.05 USDC），无需 API 密钥，无需注册。

时区和夏令时、地理距离和 geohash、哈希和 JWT 解码、机场、国家、货币和 NUTS 查询、金额拆分、进制转换等。每次调用都是一次 HTTP GET，按请求付费。

还提供面向交易 Agent 的加密衍生品数据：Bybit、Hyperliquid、dYdX、Gate、Kraken、Bitfinex、Deribit 和 OKX 的永续合约资金费率、资金费率套利、未平仓合约量、期货基差、隐含波动率、强平和订单簿深度，每次调用 $0.003 或 $0.005（下文）。

安装

npm install duo-data-utilities viem

viem 会创建用于付款的钱包账户。本软件包也依赖它。需要 Node.js 20 或更高版本。

Python（不在 PyPI 上发布，请从 GitHub 安装）：

pip install "git+https://github.com/hiesem/duo-data-utilities#subdirectory=python"

快速开始

import { privateKeyToAccount } from "viem/accounts";
import { createClient } from "duo-data-utilities";

// Your wallet holds USDC on Base. Read the key from the environment, never a literal.
const client = createClient({ account: privateKeyToAccount(process.env.DUO_PAYER_KEY as `0x${string}`) });

const iban = await client.iban.validate({ iban: "NL91 ABNA 0417 1643 00" }); // $0.05
console.log(iban.valid, iban.country); // true NL

交易对手检查

checkCounterparty 一次调用执行三项检查：IBAN（/v1/id/iban）、税号（/v1/id/national）和国家/地区（/v1/ref/country）。费用为 $0.15。

const check = await client.checkCounterparty({
  iban: "NL91 ABNA 0417 1643 00",
  country: "NL",
  taxIdType: "bsn",
  taxId: "111222333",
});
console.log(check.verdict, check.reasons); // "pass", "fail" or "review"

• fail：IBAN 或税号校验和不通过、国家/地区不是 ISO 3166-1 国家/地区，或 API 判定输入格式错误。
• review：IBAN 所属国家/地区与税号所属国家/地区不一致，或 API 不支持该国家/地区或税号类型。
• pass：所有检查均通过。

仅检查结构和校验和。此检查不会查询公司注册机构、银行或税务机关，也不会确认账户是否存在。UK 会被识别为 GB。

加密衍生品数据：永续合约资金费率、未平仓合约量、期货基差、隐含波动率、强平、订单簿深度

client.derivs 调用 https://derivs.duoleads.com：提供来自 8 家交易所（Bybit、Hyperliquid、dYdX、Gate、Kraken、Bitfinex、Deribit、OKX）的加密衍生品数据，面向交易 Agent 和机器人。包括永续期货（perp）资金费率和预测资金费率、资金费率历史数据和资金费率套利扫描器、永续合约筛选器、未平仓合约量（OI）、期货基差和期限结构、期权隐含波动率（IV）、偏斜和最大痛点、强平，以及含滑点数据的订单簿深度。每次调用 $0.003 或 $0.005，使用同一钱包和同一 x402 付款方式，无需 API 密钥。

import { privateKeyToAccount } from "viem/accounts";
import { createClient, createDerivsClient } from "duo-data-utilities";

const account = privateKeyToAccount(process.env.DUO_PAYER_KEY as `0x${string}`);
const client = createClient({ account });

const funding = await client.derivs.fundingRates({ coin: "BTC" }); // $0.003
for (const v of funding.venues) console.log(v.venue, v.apr_pct, v.next_funding_time);

const arb = await client.derivs.fundingArbitrage({ min_apr: 20, min_volume_usd: 1_000_000 }); // $0.005, all coins
const snap = await client.derivs.derivativesSnapshot({ coin: "ETH" }); // $0.005: funding, OI, basis, liquidations, long/short

// Or a derivs-only client:
const derivs = createDerivsClient({ account });
await derivs.openInterest({ coin: "SOL" }); // $0.003

import os

from eth_account import Account
from duo_data_utilities import DerivsClient, DuoClient

client = DuoClient(Account.from_key(os.environ["DUO_PAYER_KEY"]))
rates = client.derivs.funding_rates(coin="BTC")               # $0.003
book = client.derivs.orderbook(coin="BTC", size_usd=250_000)  # $0.003
derivs = DerivsClient(Account.from_key(os.environ["DUO_PAYER_KEY"]))  # derivs only

• 价格限制：client.derivs 有自己的价格上限，默认每次调用 $0.005。createClient({ account, derivs: { maxPriceUsd: 0.003 } }) 会拒绝价格为 $0.005 的路由（Python：derivs_max_price_usd=0.003）。其他规则相同：仅支持 Base USDC，付款对象仅限 0xCD673f7e1daD254347AEab6be0DEFe8b9C6b3A39，检查通过前不会签名。
• **不收费：**无效输入会免费返回 400 错误，并附带 error.expected。如果响应的交易场所数量少于路由要求，则返回 503，且不收费。两种情况都会抛出 DuoApiError。
• 响应内容就是 JSON 正文本身（没有 data 封装），包含 venues_missing、units、as_of，以及指向下一个实用路由的 see_also。TypeScript 类型包括 DerivsFundingRatesData 等。
• **币种：**BTC、btc、BTCUSDT、BTC-PERP、XBT、1000PEPE 和 kPEPE 均表示一种币。
• **MCP：**同样的 10 种工具位于 https://derivs.duoleads.com/mcp。Claude Code、Claude Desktop、Cursor 和 VS Code 的代码片段见：mcp/README.md。
• 仅提供数据，不构成投资建议，也不隶属于任何交易所。 | TypeScript | Python | 路由 | 价格 | 返回内容 | |---|---|---|---|---| | derivs.fundingRates | derivs.funding_rates | /v1/funding-rates | $0.003 | 单个币种在各交易所的永续合约资金费率：费率、8 小时费率、APR、下次结算时间、预测资金费率（包括 Binance 和 Bybit），以及最近 24 条记录 | | derivs.fundingHistory | derivs.funding_history | /v1/funding-history | $0.003 | 单个币种在单个交易所的资金费率历史，最多 30 天，包含均值、最小值、最大值和正值占比 | | derivs.fundingArbitrage | derivs.funding_arbitrage | /v1/funding-arbitrage | $0.005 | 所有币种的资金费率套利扫描器：跨平台价差最大的币种、做多和做空的平台、扣除费用后的净 APR、盈亏平衡天数 | | derivs.perpScreener | derivs.perp_screener | /v1/perp-screener | $0.005 | 永续合约筛选器：列出所有平台的全部永续合约，可按资金费率 APR、未平仓量、24 小时成交量或 24 小时涨跌幅排序 | | derivs.openInterest | derivs.open_interest | /v1/open-interest | $0.003 | 各交易所的未平仓量（OI），以币种数量和美元计，包含份额及 1 小时／4 小时／24 小时 OI 变化 | | derivs.basis | derivs.basis | /v1/basis | $0.003 | 期货基差和期限结构（年化、正向市场／反向市场）、永续合约溢价、预测资金费率 | | derivs.options | derivs.options | /v1/options | $0.003 | 隐含波动率（ATM IV）、25 delta 偏斜、看跌／看涨未平仓量比率、最大痛点、DVOL；指定一个到期日的期权链及希腊值 | | derivs.liquidations | derivs.liquidations | /v1/liquidations | $0.003 | 各平台 1-24 小时内以美元计的多头和空头清算量、总量及最大清算事件 | | derivs.orderbook | derivs.orderbook | /v1/orderbook | $0.003 | 中间价上下 0.1/0.5/1/2% 范围内的订单簿深度、价差、不平衡度、按你的订单规模计算的滑点、挂单墙 | | derivs.derivativesSnapshot | derivs.derivatives_snapshot | /v1/derivatives-snapshot | $0.005 | 一次调用即可获取快照：资金费率、未平仓量、永续合约溢价和最近基差、24 小时清算量、多空比 |

Derivs 文档：https://derivs.duoleads.com/docs · OpenAPI：https://derivs.duoleads.com/openapi.json · 索引：https://derivs.duoleads.com/llms.txt · 条款：https://derivs.duoleads.com/terms · 隐私：https://derivs.duoleads.com/privacy

SEO 关键词数据：搜索量、CPC、关键词难度、关键词建议、Google Trends

client.keywords 会调用 https://keywords.duoleads.com。它会返回 Google 关键词搜索量、CPC、竞争度、关键词难度和搜索意图（Google Ads 数据）、种子词的关键词建议，以及 Google Trends 数据（随时间变化的关注度、相关查询、按地区划分的关注度）。每次调用费用为 $0.03 至 $0.045，使用同一个钱包和相同的 x402 付款方式，无需 API 密钥。

const volume = await client.keywords.searchVolume({ keywords: ["phone", "watch"], country: "us" }); // $0.04, up to 20 keywords
const overview = await client.keywords.keywordOverview({ keywords: myList });                        // $0.04, up to 100 keywords (POST)
const ideas = await client.keywords.keywordIdeas({ keyword: "seo api", limit: 50 });                 // $0.04 (POST)
const trend = await client.keywords.trend({ keyword: "seo tools", timeframe: "past_12_months" });    // $0.045

// Or a keywords-only client:
const keywords = createKeywordsClient({ account });
await keywords.relatedQueries({ keyword: "seo api", country: "us" }); // $0.03

• 价格限制： client.keywords 有自己的调用限额，默认每次调用为 $0.045。createClient({ account, keywords: { maxPriceUsd: 0.04 } }) 会拒绝 $0.045 的趋势路由。其他规则相同：仅限 Base USDC，只能支付给 0xCD673f7e1daD254347AEab6be0DEFe8b9C6b3A39，且检查通过前不会签名。
• 错误： 无效输入会返回免费的 400 错误。上游故障会返回 503，并提示“未扣费”。两种情况都会抛出 DuoApiError。
• MCP： 相同的 6 个工具位于 https://keywords.duoleads.com/mcp。

方法	路由	价格	返回内容
keywords.keywordOverview	POST /v1/keyword-overview	$0.04	1 至 100 个关键词的搜索量、CPC、竞争度、关键词难度和搜索意图
keywords.searchVolume	GET /v1/search-volume	$0.04	同一国家/地区中 1 至 20 个关键词的相同指标
keywords.keywordIdeas	POST /v1/keyword-ideas	$0.04	一个种子词最多 100 个相关关键词建议，每个建议都包含相同指标
keywords.trend	GET /v1/trend	$0.045	Google Trends 随时间变化的关注度（0-100），时间范围为 7 天至 5 年
keywords.relatedQueries	GET /v1/related-queries	$0.03	Google Trends 热门和上升中的相关查询
keywords.interestByRegion	GET /v1/interest-by-region	$0.03	某个国家/地区各地区的 Google Trends 关注度

关键词文档：https://keywords.duoleads.com/docs · OpenAPI：https://keywords.duoleads.com/openapi.json · 索引：https://keywords.duoleads.com/llms.txt

方法

每种方法每次调用收费 $0.05。每种方法的 JSDoc 都会说明路由和参数。client.call(path, params) 可调用任意路由，client.callWithReceipt(path, params) 还会返回结算收据。

方法	路由	功能说明
iban.validate	/v1/id/iban	IBAN 验证器：长度、mod-97 校验位、银行／分行／账户拆分（89 个国家）
iban.generate	/v1/id/iban-build	IBAN 生成器：根据国家和 BBAN 或银行／分行／账户构建 IBAN，并计算校验位
taxId.validate	/v1/id/national	VAT、税号和国家身份证件号码验证器：23 个国家，仅校验校验和（VAT 格式包括 BE、DE、FR、IT、PL、AT、CH、IE）
isin.validate	/v1/id/security	ISIN 验证器，以及 CUSIP、SEDOL 和 FIGI 校验位验证；根据 NSIN 构建 ISIN
barcode.validate	/v1/id/gs1	GTIN 条码验证器：EAN-13、UPC-A（GTIN-12）、GTIN-8/14、GLN 和 SSCC 校验位
timezone.convert	/v1/time/zone	时区转换器：将某个时刻转换为 IANA 时区的当地时间，也可反向转换，并提供 UTC 偏移量和夏令时状态
timezone.dstTransitions	/v1/time/dst	夏令时转换：指定 IANA 时区即将发生的夏令时变更
businessDays.calculate	/v1/time/business-days	工作日计算器：根据周末设置和节假日列表添加或统计工作日
rrule.expand	/v1/time/rrule	RRULE 展开器：将 RFC 5545 重复规则转换为具体的发生日期
calendar.convert	/v1/time/calendar	历法转换器：将公历转换为回历、希伯来历、日本年号、波斯历等，并提供复活节日期
text.similarity	/v1/text/similarity	字符串相似度：Levenshtein、Jaro-Winkler 距离和 Soundex/Metaphone 语音键
text.slug	/v1/text/slug	Slug 生成器：支持 Unicode 的 URL slug，并进行转写
text.transliterate	/v1/text/transliterate	西里尔字母转写为拉丁字母（ISO 9:1995、BGN/PCGN 俄语）
text.unicode	/v1/text/unicode	Unicode 规范化（NFC/NFKC）、文字系统检测和同形异义字符／易混淆字符检查
hash.generate	/v1/code/hash	哈希生成器：SHA-256、SHA-512、SHA-3、Keccak-256、BLAKE2 和 HMAC 摘要
punycode.convert	/v1/code/idn	Punycode 转换器：将 IDN 域名转换为 ASCII，或反向转换，并进行 IDNA2008 标签验证
jwt.decode	/v1/code/jwt	JWT 解码器：解析标头、声明和过期状态（不验证签名）
semver.compare	/v1/code/semver	Semver 解析器：解析和比较版本，检查是否符合版本范围
url.parse	/v1/code/url	URL 解析器：解析、规范化并提取可注册域名（eTLD+1）
geohash.encodeDecode	/v1/geo/geohash	Geohash 编码和解码器，支持相邻单元格
plusCode.encodeDecode	/v1/geo/pluscode	Plus code（Open Location Code）编码和解码器
polygon.check	/v1/geo/polygon	检查点是否位于多边形内，并计算 GeoJSON 的边界框、质心和面积
distance.calculate	/v1/geo/distance	距离计算器：计算 WGS-84 上的测地线距离、方位角和目标点
cryptoAddress.validate	/v1/chain/address	加密货币地址验证器：识别区块链并验证校验和（EVM、Bitcoin、Solana 等）
solidity.selector	/v1/chain/selector	Solidity 函数选择器：根据签名计算 Keccak-256、4 字节选择器和事件主题
airport.lookup	/v1/ref/airport	根据 IATA 或 ICAO 代码查询机场：名称、坐标、海拔、时区；查询附近机场
country.lookup	/v1/ref/country	国家查询：ISO 3166 代码、货币、顶级域名、联合国区域和 ISO 3166-2 行政区划
currency.lookup	/v1/ref/currency	货币查询：ISO 4217 代码、名称、最小单位和现金舍入规则
nuts.lookup	/v1/ref/nuts	NUTS 区域查询：欧盟统计区域代码、名称和层级
money.split	/v1/num/allocate	金额拆分：将金额分配为多个份额，不产生舍入误差
base.convert	/v1/num/radix	进制转换器：在 2 到 36 进制之间转换整数（十六进制、二进制、八进制）
statistics.calculate	/v1/num/stats	统计计算器：平均值、中位数、标准差、四分位数和百分位数
numberWords.convert	/v1/num/words	将数字转换为 12 种语言的文字形式，支持序数和货币格式

MCP

MCP 服务位于 https://api.duoleads.com/mcp（Streamable HTTP）。tools/list 免费。每次 tools/call 收费 $0.05，需要支持 x402 的客户端或钱包桥接。衍生品工具位于第二个服务 https://derivs.duoleads.com/mcp，每次调用收费 $0.003 或 $0.005。Claude Code、Claude Desktop、Cursor、VS Code 和 AgentCash 的相关说明请参阅 mcp/README.md。

Python

需要 Python 3.10 或更高版本。客户端带有类型标注（py.typed），使用 requests 和 x402 的 EVM 签名器。路由和方法名称与 TypeScript 客户端一致，采用 snake_case。

import os

from eth_account import Account
from duo_data_utilities import DuoClient

client = DuoClient(Account.from_key(os.environ["DUO_PAYER_KEY"]))  # your wallet, never a literal key
print(client.iban.validate(iban="NL91 ABNA 0417 1643 00")["valid"])

check = client.check_counterparty(iban="NL91 ABNA 0417 1643 00", country="NL", tax_id_type="bsn", tax_id="111222333")
print(check.verdict, check.reasons)

DuoClient(account, *, max_price_usd=0.05, timeout=None, pay_to=<service address>) 会应用相同的价格保护。传入 session= 和一个已经负责付款的 requests.Session，即可跳过价格保护。from_ 是 Python 中用于表示 from 查询参数的名称。

定价和价格保护

• 每个主 API 路由每次调用收费 $0.05，以 USDC 在 Base（eip155:8453）上通过 x402 v2 付款。衍生品路由每次调用收费 $0.003 或 $0.005，并有各自的限额（默认 $0.005）；请参阅衍生品部分。
• maxPriceUsd 默认值为 0.05。在签署任何内容之前，如果付款要求的金额超过该值、网络不是 Base、资产不是 Base USDC，或收款方不是指定地址，客户端都会拒绝。被拒绝的调用不会付款，并会抛出 PriceGuardError。
• 客户端只会向服务的公开地址 0xCD673f7e1daD254347AEab6be0DEFe8b9C6b3A39 签署付款（payTo 选项；Python 中为 pay_to）。如果将 baseUrl 指向其他部署，请设置此选项。
• 客户端不会自行重试已付款的调用。
• 除环回地址（localhost、127.0.0.1、[::1]）外，客户端会拒绝普通的 http://。
• 使用 fetch 而不是 account 时，传入的 fetch 必须已经负责付款。价格保护无法检查其中进行的付款，因此请使用 account 来保留价格保护。

示例

examples/ 中提供了可运行的 Agent。每个文件夹都包含一个 README，介绍设置、环境变量和费用。

示例	语言	功能
supplier-onboarding-agent	TypeScript	供应商入驻检查：生成并验证 IBAN、检查 VAT 号码、比对账户持有人姓名。针对每位供应商进行批准、审核或拒绝。
kyb-payout-agent-python	Python	使用 Claude 工具的 KYB 付款验证 Agent：检查 IBAN、VAT / 税号、国家和姓名，并设有支出上限。
mcp-paid-client	TypeScript	用于 https://api.duoleads.com/mcp 的 MCP 客户端，使用 x402 为每次 tools/call 付款，并提供 MCP 主机配置。
funding-arbitrage-watcher	TypeScript	资金费率套利监控器：每隔几分钟扫描 8 家交易所的永续合约资金费率价差，并在发现新的扣除费用后的套利机会时发出提醒。每次扫描 $0.005；默认运行费用为 $0.06。
derivs-snapshot-loop-python	Python	按币种循环生成衍生品快照：获取每种币的资金费率、未平仓合约、基差、清算数据和多空比；标记仓位拥挤的情况。每轮每种币 $0.005；默认运行费用为 $0.06。
keyword-research-agent	TypeScript	SEO 关键词研究 Agent：提供关键词建议及其搜索量、每次点击费用和难度，按机会排序，并对最佳选择进行 Google Trends 检查。默认运行（1 个种子词）费用为 $0.085。
node-basic.ts	TypeScript	在一个脚本中完成 IBAN、时区、交易对手检查和结算收据生成。
vercel-ai-sdk-tool.ts	TypeScript	将 IBAN 和交易对手检查作为 Vercel AI SDK 工具。
langchain_tool.py	Python	将 IBAN 和交易对手检查作为 LangChain 工具。
claude-mcp.md		将 MCP 服务添加到 Claude Code。

主要 API 调用费用为 $0.05，衍生品调用费用为 $0.003 或 $0.005，关键词调用费用为 $0.03 至 $0.045，均以 Base 上的 USDC 计价，由你配置的钱包支付。示例测试会使用模拟响应离线运行；CI 中不会发生任何付款。

User-Agent 和隐私

SDK 会发送标明 SDK 和版本的 User-Agent；API 仅存储粗略的客户端类别，详见 https://api.duoleads.com/privacy

• TypeScript：duo-data-utilities-js/<version> (+https://github.com/hiesem/duo-data-utilities)。可通过 createClient({ userAgent }) 覆盖，也可附加你自己的产品名称：userAgent: `${SDK_USER_AGENT} my-agent/1.0` 。
• Python：duo-data-utilities-py/<version> (+https://github.com/hiesem/duo-data-utilities)。可通过 DuoClient(..., user_agent=...) 覆盖，也可附加到 duo_data_utilities.USER_AGENT。
• 浏览器中的页面无法设置 User-Agent，因此客户端不会在浏览器中发送 User-Agent，也不会用其他标头替代（否则浏览器会发送 CORS 预检请求，而 API 不接受该请求）。浏览器会改为发送自身的 User-Agent。

本项目不提供什么

• 不是注册信息查询服务。IBAN、税号和 VAT 检查仅验证结构和校验和。
• 不提供金融、法律或税务建议。每个响应都附有免责声明。
• 衍生品数据仅为数据：不构成投资建议，不是基准数据，也不隶属于任何交易所。

链接

• API 文档：https://api.duoleads.com/docs
• OpenAPI：https://api.duoleads.com/openapi.json
• 机器可读索引：https://api.duoleads.com/llms.txt
• 条款：https://api.duoleads.com/terms
• 隐私：https://api.duoleads.com/privacy

HTTP 路由也可在不使用此 SDK 的情况下运行。未付款的 GET 请求会返回 402 Payment Required 和 PAYMENT-REQUIRED 标头，任何 x402 v2 客户端都可以为该挑战付款。

开发

npm install
npm run generate        # rebuild src/generated.ts and src/derivs-generated.ts from spec/ (npm test checks they are current)
python3 python/scripts/generate.py   # the same for the Python package
npm run typecheck
npm test
npm run build

spec/ 存放代码生成所依据的快照。详见 spec/README.md。

许可证

MIT。详见 LICENSE。