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

IBAN、ISIN、VAT／税 ID、GTIN バーコードの検証に加え、AI エージェント向けのユーティリティをさらに 29 種類利用できます。呼び出しごとに支払い（x402 経由で Base 上の $0.05 USDC）、API キー不要、登録不要です。

タイムゾーンと DST、地理的距離とジオハッシュ、ハッシュと JWT のデコード、空港・国・通貨・NUTS の検索、金額の分割、基数変換などに対応しています。各呼び出しは HTTP GET 1 回で、リクエストごとに支払います。

さらに、取引エージェント向けの暗号資産デリバティブデータも利用できます。Bybit、Hyperliquid、dYdX、Gate、Kraken、Bitfinex、Deribit、OKX を対象に、無期限先物の資金調達率、資金調達アービトラージ、建玉、先物ベーシス、インプライド・ボラティリティ、清算、オーダーブックの厚みを、呼び出しごとに $0.003 または $0.005 で取得できます（以下を参照）。

インストール

npm install duo-data-utilities viem

支払いを行うウォレットアカウントは、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 は 1 回の呼び出しで 3 つの確認を実行します。IBAN（/v1/id/iban）、税 ID（/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 または税 ID のチェックサムが無効である、国が ISO 3166-1 の国ではない、または API が入力を不正な形式として拒否した場合です。
• review：IBAN の国と税 ID の国が異なる、または API がその国や税 ID の種類に対応していない場合です。
• pass：すべての確認に合格した場合です。

確認するのは形式とチェックサムのみです。会社登記簿、銀行、税務当局への照会は行わず、口座の存在も確認しません。UK は GB として扱われます。

暗号資産デリバティブデータ：無期限先物の資金調達率、建玉、先物ベーシス、インプライド・ボラティリティ、清算、オーダーブックの厚み

client.derivs は https://derivs.duoleads.com を呼び出します。取引エージェントやボット向けに、8 つの取引所（Bybit、Hyperliquid、dYdX、Gate、Kraken、Bitfinex、Deribit、OKX）の暗号資産デリバティブデータを提供します。予測値を含む無期限先物（perp）の資金調達率、資金調達率の履歴と資金調達アービトラージスキャナー、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 のみで、チェックが終わるまで署名は行われません。
• **課金されない場合：**入力が不正な場合は、error.expected を含む 400 が無料で返されます。ルートに必要な数の取引所から応答がない場合は 503 が返され、課金されません。どちらの場合も DuoApiError がスローされます。
• 応答：data エンベロープのない JSON 本体で、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 | 1つのコインについて、取引所ごとの無期限先物のファンディングレート：レート、8時間レート、APR、次回のファンディング、予測ファンディング（Binance と Bybit を含む）、直近24回の記録 | | derivs.fundingHistory | derivs.funding_history | /v1/funding-history | $0.003 | 1つのコインについて、1つの取引所における最大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）。コイン建てとUSD建ての数量、シェア、1時間／4時間／24時間のOI変動を含む | | derivs.basis | derivs.basis | /v1/basis | $0.003 | 先物ベーシスとタームストラクチャー（年率換算、コンタンゴ／バックワーデーション）、無期限先物プレミアム、予測ファンディング | | derivs.options | derivs.options | /v1/options | $0.003 | インプライドボラティリティ（ATM IV）、25デルタ・スキュー、プット／コールOI比率、最大ペイン、DVOL；1つの満期を対象とした、ギリシャ指標付きオプションチェーン | | derivs.liquidations | derivs.liquidations | /v1/liquidations | $0.003 | 1～24時間における取引所ごとのロングおよびショートの清算額（USD）、合計額、最大の清算イベント | | derivs.orderbook | derivs.orderbook | /v1/orderbook | $0.003 | ミッド価格から0.1／0.5／1／2％以内の板の厚さ、スプレッド、不均衡、注文サイズに応じたスリッページ、注文の壁 | | derivs.derivativesSnapshot | derivs.derivatives_snapshot | /v1/derivatives-snapshot | $0.005 | 1回の呼び出しで取得できるスナップショット：ファンディング、建玉、無期限先物プレミアムと最も近いベーシス、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（関心度の推移、関連クエリ、地域別の関心度）を返します。呼び出し料金は 1 回あたり $0.03〜$0.045 で、API キーは不要です。同じウォレットと x402 決済を使用します。

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 には個別の上限があり、デフォルトでは 1 回あたり $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 つの国の 1〜20 個のキーワードについて、同じ指標を返します
keywords.keywordIdeas	POST /v1/keyword-ideas	$0.04	1 つのシードに関連する最大 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

メソッド

各メソッドの呼び出し料金は 1 回あたり $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、納税者番号、国民 ID のバリデーター：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	文字列類似度：レーベンシュタイン距離、Jaro-Winkler 距離、Soundex／Metaphone の音声キー
text.slug	/v1/text/slug	スラッグ生成ツール：音訳に対応した Unicode 対応 URL スラッグ
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 パーサー：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 コード、通貨、TLD、国連地域、ISO 3166-2 の下位区分
currency.lookup	/v1/ref/currency	通貨の検索：ISO 4217 コード、名称、補助単位、現金の丸め処理
nuts.lookup	/v1/ref/nuts	NUTS 地域の検索：EU 統計地域コード、名称、階層
money.split	/v1/num/allocate	金額の分割：丸め誤差なく金額を複数の分け前に割り当てます
base.convert	/v1/num/radix	基数変換ツール：2 から 36 までの基数間で整数を変換します（16 進数、2 進数、8 進数）
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 対応クライアントまたはウォレットブリッジが必要です。デリバティブツールは、2 つ目のサーバー https://derivs.duoleads.com/mcp で提供されています（1 回あたり $0.003 または $0.005）。Claude Code、Claude Desktop、Cursor、VS Code、AgentCash については、mcp/README.md をご覧ください。

Python

Python 3.10 以降が必要です。クライアントは型付けされており（py.typed）、x402 の EVM 署名機能を備えた requests を使用します。ルート名とメソッド名は 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>) は、同じ価格ガードを適用します。すでに支払い機能を備えた requests.Session を session= に渡すと、価格ガードをスキップできます。from_ は、from クエリパラメーターに対応する Python での名前です。

料金と価格ガード

• メイン API の各ルートの料金は 1 回あたり $0.05 で、x402 v2 を使用して Base（eip155:8453）上の USDC で支払います。Derivs ルートの料金は $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:// は拒否されます。
• account の代わりに fetch を使用する場合は、すでに支払い機能を備えた fetch を渡します。価格ガードはその内部で行われる支払いを確認できないため、ガードを維持するには account を使用してください。

例

examples/ に実行可能なエージェントがあります。各フォルダーには、セットアップ、環境変数、費用を記載した README があります。

例	言語	機能
supplier-onboarding-agent	TypeScript	サプライヤー／ベンダーのオンボーディング確認：IBAN を作成して検証し、VAT 番号を確認し、口座名義を照合します。サプライヤーごとに承認、要確認、または却下します。
kyb-payout-agent-python	Python	Claude のツール使用による KYB 支払い検証エージェント：IBAN、VAT／税 ID、国、名前を確認し、支出上限を設定します。
mcp-paid-client	TypeScript	https://api.duoleads.com/mcp 用の MCP クライアントです。各 tools/call の支払いに x402 を使用し、MCP ホスト設定も備えています。
funding-arbitrage-watcher	TypeScript	資金調達率のアービトラージ監視ツール：数分ごとに 8 つの取引所における無期限先物の資金調達率スプレッドをスキャンし、手数料調整後の新たな機会を検出すると通知します。スキャン 1 回あたり $0.005 で、デフォルトの実行費用は $0.06 です。
derivs-snapshot-loop-python	Python	コインごとのデリバティブスナップショットループ：各コインの資金調達率、建玉、ベーシス、清算、ロング／ショートを取得し、ポジションの偏りを検出します。ラウンドごとにコイン 1 枚あたり $0.005 で、デフォルトの実行費用は $0.06 です。
keyword-research-agent	TypeScript	SEO キーワード調査エージェント：検索ボリューム、CPC、難易度を含むキーワード候補を機会順に並べ、最有力候補について Google Trends で確認します。デフォルトの実行（シード 1 件）の費用は $0.085 です。
node-basic.ts	TypeScript	1 つのスクリプトで IBAN、タイムゾーン、取引相手を確認し、決済レシートを作成します。
vercel-ai-sdk-tool.ts	TypeScript	IBAN と取引相手の確認を Vercel AI SDK のツールとして実行します。
langchain_tool.py	Python	IBAN と取引相手の確認を LangChain のツールとして実行します。
claude-mcp.md		Claude Code に MCP サーバーを追加します。

主な 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、税 ID、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 をご覧ください。