voulti

加盟店向けの暗号資産決済ゲートウェイです。5つのネットワークでUSDC、USDT、ステーブルコインを受け付けます。

アーキテクチャ

apps/
  checkout/     React + Vite — customer payment page
  merchant/     Next.js — merchant dashboard
  api/          Fastify — backend API

contracts/
  core/         DerampProxy + modules (Hardhat, Solidity ^0.8.28)

packages/
  shared/       Shared utilities

assets/
  brand/        The logo, and the icons every app is derived from

ネットワーク

ネットワーク	Chain ID	トークン
Celo	42220	USDC, USDT, COPm
Arbitrum	42161	USDC, USD₮0
Polygon	137	USDC, USDT0
Base	8453	USDC
BSC	56	USDC, USDT

AI エージェント向け

Voultiはエンドツーエンドでエージェントから利用できます。統合APIにAPIキーは不要です。

• MCP サーバー：claude mcp add voulti -- npx -y voulti-mcp — ツールはcreate_invoice、get_invoice、get_payment_linkです。詳しくはmcp/README.mdをご覧ください。
• エージェントスキル：npx skills add csacanam/voulti — またはvoulti.com/skill.mdをご覧ください。
• HTTPのみ：POST https://api.voulti.com/invoicesに{ commerce_id, amount_fiat, reference? }を送信すると、ホスト型のチェックアウトリンクが返されます。LLM向けインデックス：voulti.com/llms.txt。

機能

• セルフサービス登録 — 加盟店はウォレットを接続し、事業名を入力するだけで完了します
• 2つの決済方法 — ウォレットを接続、またはアドレスで支払う（QRコード＋入金）
• マルチチェーン残高 — トークンごとに集計し、ネットワークを自動選択します
• 資金の送金 — ダッシュボードから任意のウォレットへ出金できます
• HDウォレットのスイープ — 入金を自動検出して決済します
• 一部入金／過入金への対応 — 過入金は自動返金し、一部入金は待機します
• i18n — スペイン語と英語

スマートコントラクト

5つのネットワークにデプロイされたモジュラープロキシアーキテクチャです。

• DerampProxy — エントリーポイント。呼び出しを各モジュールにルーティングします
• DerampStorage — 集中型データストア
• AccessManager — ロール、トークン／加盟店のホワイトリスト管理
• InvoiceManager — 請求書のライフサイクル管理
• PaymentProcessor — 決済の実行、手数料の計算
• TreasuryManager — サービス手数料の回収
• WithdrawalManager — 加盟店資金の出金

すべてのアドレスについては、contracts/core/deployed-addresses/PRODUCTION.mdをご覧ください。

オペレーターウォレット

0x21581Cb82D9a66126fBe7639f4AF55DdfEA48E26 — コントラクトをデプロイし、加盟店をホワイトリストに登録し、HDウォレットのスイープ用にガスを送金します。

ローカル開発

# Prerequisites: Node 18+, pnpm
pnpm install
cd contracts/core && npm install

# Start Hardhat node (terminal 1)
npx hardhat node

# Deploy + setup (terminal 2)
cd contracts/core
npx hardhat run scripts/setup-local.ts --network localhost

# Start API (terminal 3)
pnpm dev:api

# Start checkout (terminal 4)
pnpm dev:checkout

# Start merchant dashboard (terminal 5)
pnpm dev:merchant

API エンドポイント

メソッド	パス	認証	説明
POST	/commerces	Privy	加盟店を登録
GET	/commerces/:id	Public	加盟店情報
GET	/commerces/:id/balances	Privy	マルチチェーン残高
POST	/invoices	Privy	請求書を作成
GET	/invoices/:id	Public	請求書の詳細＋トークン
POST	/blockchain/create	Public	オンチェーン請求書を作成
GET	/blockchain/status/:id	Public	オンチェーン請求書のステータス
POST	/deposit/generate	Public	HD入金アドレスを生成
GET	/deposit/status/:id	Public	入金の監視ステータス
GET	/stats	Public	売上統計（公開しながら構築中）
GET	/prices/rates	Public	DBから取得した法定通貨およびトークンのレート
POST	/prices/update-fiat-rates	Cron	法定通貨レート（OpenExchangeRates）を更新
POST	/prices/update-token-prices	Cron	トークン価格（CoinGecko）を更新

Cronジョブ

DigitalOcean（または任意のスケジューラー）で、これらをスケジュール済みジョブとして設定してください。

ジョブ	URL	スケジュール	説明
法定通貨レート	POST /prices/update-fiat-rates	毎時	OpenExchangeRatesからUSD→COP/EUR/BRL/MXN/ARSのレートを更新します
トークン価格	POST /prices/update-token-prices	毎時	CoinGeckoからUSDC/USDT/COPmのレートを更新します
請求書の期限切れ処理	POST /orders/expire-orders	毎分	期限切れの請求書をExpiredにします
メールの処理	POST /notifications/process-emails	毎分	Resend経由で決済確認メールを送信します
Webhookの処理	POST /notifications/process-url-confirmations	毎分	加盟店の確認URLを呼び出します

ベースURL：https://api.voulti.com

次の環境変数が必要です：OPENEXCHANGERATE_APPID、COINGECKO_APIKEY、RESEND_APIKEY。

環境変数

必要な変数については、.env.example を参照してください。