# voulti [Health: Active]

**Category:** 💰 Finance & Fintech  
**Repository:** https://github.com/csacanam/voulti  
**GitHub Stars:** 0  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/voulti

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

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "voulti": {
    "command": "npx",
    "args": ["-y","voulti-mcp"]
  }
}
```

## Documentation & README

<img src="https://raw.githubusercontent.com/csacanam/voulti/HEAD/assets/brand/voulti-wordmark.png" alt="Voulti" width="212">

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

| Network | Chain ID | Tokens |
|---------|----------|--------|
| Celo | 42220 | USDC, USDT, COPm |
| Arbitrum | 42161 | USDC, USD₮0 |
| Polygon | 137 | USDC, USDT0 |
| Base | 8453 | USDC |
| BSC | 56 | USDC, 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`](https://github.com/csacanam/voulti/blob/HEAD/mcp/README.md).
- **Agent skill**: `npx skills add csacanam/voulti` — or read it at [voulti.com/skill.md](https://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](https://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](https://github.com/csacanam/voulti/blob/HEAD/contracts/core/deployed-addresses/PRODUCTION.md) for all addresses.

## Operator Wallet

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

## Local Development

```bash
# 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

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| POST | /commerces | Privy | Register commerce |
| GET | /commerces/:id | Public | Commerce info |
| GET | /commerces/:id/balances | Privy | Multi-chain balances |
| POST | /invoices | Privy | Create invoice |
| GET | /invoices/:id | Public | Invoice details + tokens |
| POST | /blockchain/create | Public | Create on-chain invoice |
| GET | /blockchain/status/:id | Public | On-chain invoice status |
| POST | /deposit/generate | Public | Generate HD deposit address |
| GET | /deposit/status/:id | Public | Deposit monitoring status |
| GET | /stats | Public | Revenue stats (building in public) |
| GET | /prices/rates | Public | Fiat + token rates from DB |
| POST | /prices/update-fiat-rates | Cron | Update fiat rates (OpenExchangeRates) |
| POST | /prices/update-token-prices | Cron | Update token prices (CoinGecko) |

## Cron Jobs

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

| Job | URL | Schedule | Description |
|-----|-----|----------|-------------|
| Fiat rates | `POST /prices/update-fiat-rates` | Every hour | Updates USD→COP/EUR/BRL/MXN/ARS rates from OpenExchangeRates |
| Token prices | `POST /prices/update-token-prices` | Every hour | Updates USDC/USDT/COPm rates from CoinGecko |
| Expire invoices | `POST /orders/expire-orders` | Every minute | Marks expired invoices as Expired |
| Process emails | `POST /notifications/process-emails` | Every minute | Sends payment confirmation emails via Resend |
| Process webhooks | `POST /notifications/process-url-confirmations` | Every minute | Calls commerce confirmation URLs |

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

Requires env vars: `OPENEXCHANGERATE_APPID`, `COINGECKO_APIKEY`, `RESEND_APIKEY`.

## Environment Variables

See [.env.example](https://github.com/csacanam/voulti/blob/HEAD/.env.example) for all required variables.