English Français العربية

io.github.csacanam/voulti

السجل الرسمي المالية والمدفوعات

Accept crypto payments from AI agents: invoices + hosted checkout on 5 chains. No API key.

الشيفرة المصدرية التوثيق

ماذا يمكنك أن تفعل مع io.github.csacanam/voulti؟

  • Self-service registration — merchant connects wallet, names business, done
  • Two payment methods — Connect Wallet or Pay by Address (QR + deposit)
  • Multi-chain balances — aggregated by token, network auto-selected
  • Send funds — withdraw to any wallet from dashboard
  • HD wallet sweep — automatic deposit detection and settlement
  • Partial/over payment handling — auto-refund on overpay, wait on partial
  • i18n — Spanish and English

التثبيت

أضف هذا إلى إعدادات MCP في عميلك (Claude Desktop: claude_desktop_config.json، وCursor: ‏.cursor/mcp.json، ويستخدم VS Code وغيره الصيغة نفسها «mcpServers»).

NPM package voulti-mcp
Claude Code 
claude mcp add voulti -e 'VOULTI_COMMERCE_ID=<VOULTI_COMMERCE_ID>' -- npx -y voulti-mcp@0.1.0
إعداد JSON (Claude Desktop وCursor وVS Code) 
{
    "mcpServers": {
        "voulti": {
            "command": "npx",
            "args": [
                "-y",
                "voulti-mcp@0.1.0"
            ],
            "env": {
                "VOULTI_COMMERCE_ID": "<VOULTI_COMMERCE_ID>"
            }
        }
    }
}

متغيرات البيئة

  • VOULTI_COMMERCE_ID Default merchant id (from app.voulti.com → Receive Payments → Developers). Optional — can be passed per call.

التوثيق

مأخوذ من ملف README للمشروع على GitHub ويُحدَّث أسبوعيًا. تفتح الروابط على GitHub.

المحتويات
  1. Architecture
  2. Networks
  3. For AI agents
  4. Features
  5. Smart Contracts
  6. Operator Wallet
  7. Local Development
  8. API Endpoints
  9. Cron Jobs
  10. Environment Variables

Crypto payment gateway for merchants. Accept USDC, USDT and stablecoins on 5 networks.

Architecture

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

Networks

NetworkChain IDTokens
Celo42220USDC, USDT, COPm
Arbitrum42161USDC, USD₮0
Polygon137USDC, USDT0
Base8453USDC
BSC56USDC, USDT

For AI agents

Voulti is agent-usable end to end — the integration API needs no API key:

  • MCP server: claude mcp add voulti -- npx -y voulti-mcp — tools create_invoice, get_invoice, get_payment_link. See mcp/README.md.
  • Agent skill: npx skills add csacanam/voulti — or read it at voulti.com/skill.md.
  • Plain HTTP: POST https://api.voulti.com/invoices with { commerce_id, amount_fiat, reference? } → hosted checkout link. LLM index: voulti.com/llms.txt.

Features

  • Self-service registration — merchant connects wallet, names business, done
  • Two payment methods — Connect Wallet or Pay by Address (QR + deposit)
  • Multi-chain balances — aggregated by token, network auto-selected
  • Send funds — withdraw to any wallet from dashboard
  • HD wallet sweep — automatic deposit detection and settlement
  • Partial/over payment handling — auto-refund on overpay, wait on partial
  • i18n — Spanish and English

Smart Contracts

Modular proxy architecture deployed on 5 networks:

  • DerampProxy — entry point, routes calls to modules
  • DerampStorage — centralized data store
  • AccessManager — roles, token/commerce whitelisting
  • InvoiceManager — invoice lifecycle
  • PaymentProcessor — payment execution, fee calculation
  • TreasuryManager — service fee collection
  • WithdrawalManager — commerce fund withdrawals

See contracts/core/deployed-addresses/PRODUCTION.md for all addresses.

Operator Wallet

0x21581Cb82D9a66126fBe7639f4AF55DdfEA48E26 — deploys contracts, whitelists commerces, sends gas for HD wallet sweeps.

Local Development

# 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 Endpoints

MethodPathAuthDescription
POST/commercesPrivyRegister commerce
GET/commerces/:idPublicCommerce info
GET/commerces/:id/balancesPrivyMulti-chain balances
POST/invoicesPrivyCreate invoice
GET/invoices/:idPublicInvoice details + tokens
POST/blockchain/createPublicCreate on-chain invoice
GET/blockchain/status/:idPublicOn-chain invoice status
POST/deposit/generatePublicGenerate HD deposit address
GET/deposit/status/:idPublicDeposit monitoring status
GET/statsPublicRevenue stats (building in public)
GET/prices/ratesPublicFiat + token rates from DB
POST/prices/update-fiat-ratesCronUpdate fiat rates (OpenExchangeRates)
POST/prices/update-token-pricesCronUpdate token prices (CoinGecko)

Cron Jobs

Configure these as scheduled jobs in DigitalOcean (or any scheduler):

JobURLScheduleDescription
Fiat ratesPOST /prices/update-fiat-ratesEvery hourUpdates USD→COP/EUR/BRL/MXN/ARS rates from OpenExchangeRates
Token pricesPOST /prices/update-token-pricesEvery hourUpdates USDC/USDT/COPm rates from CoinGecko
Expire invoicesPOST /orders/expire-ordersEvery minuteMarks expired invoices as Expired
Process emailsPOST /notifications/process-emailsEvery minuteSends payment confirmation emails via Resend
Process webhooksPOST /notifications/process-url-confirmationsEvery minuteCalls commerce confirmation URLs

Base URL: https://api.voulti.com

Requires env vars: OPENEXCHANGERATE_APPID, COINGECKO_APIKEY, RESEND_APIKEY.

Environment Variables

See .env.example for all required variables.

الأسئلة الشائعة

ما هو io.github.csacanam/voulti؟

Accept crypto payments from AI agents: invoices + hosted checkout on 5 chains. No API key.

كيف أثبّت io.github.csacanam/voulti؟

يعمل على جهازك. في Claude Code: claude mcp add voulti -e 'VOULTI_COMMERCE_ID=<VOULTI_COMMERCE_ID>' -- npx -y voulti-mcp@0.1.0. وفي العملاء الآخرين، الصق إعداد JSON من هذه الصفحة في إعدادات MCP الخاصة بهم.

هل يحتاج io.github.csacanam/voulti إلى مفتاح API؟

لا يذكر إدراجه في السجل أي مفتاح أو سر إلزامي. قد تتطلب بعض الميزات حسابًا لدى الخدمة التي يتصل بها.

هل io.github.csacanam/voulti مفتوح المصدر؟

نعم. شيفرته متاحة على GitHub بترخيص MIT.

من يصون io.github.csacanam/voulti؟

ينشره csacanam. يدرجه AI.tn لكنه لا يصونه ولا يوصي به.

من سجل MCP الرسمي. الإدراج ليس توصية: راجع شيفرة الخادم وصلاحياته قبل منحه الوصول إلى بياناتك.