# InvoCoin — Non-Custodial Cryptocurrency Payment Infrastructure

> InvoCoin (https://invocoin.xyz) is a production cryptocurrency payment infrastructure platform for businesses. It provides invoicing, subscription billing, hosted checkout sessions, and stablecoin payment acceptance across multiple EVM-compatible blockchains. The platform is designed for B2B and B2C commerce, combining traditional finance UX patterns with non-custodial Web3 architecture. Users retain full control of their private keys at all times.

---

## Company & Product

- **Product name**: InvoCoin
- **Domain**: https://invocoin.xyz
- **Category**: Cryptocurrency payment infrastructure / Web3 fintech
- **Target users**: Businesses, freelancers, SaaS companies, and service providers accepting stablecoin payments
- **Business model**: Payment infrastructure platform (similar to Stripe for crypto)
- **Status**: Production platform with smart contract deployment and on-chain verification infrastructure

---

## Security Architecture

InvoCoin follows a non-custodial security model. The platform never has access to users' private keys, mnemonics, or wallet passwords. All cryptographic operations occur client-side in the browser.

### HD Wallet System
- **Standard**: BIP-39 mnemonic generation (128 bits of entropy, 12-word recovery phrase)
- **Derivation**: BIP-44 hierarchical deterministic paths (m/44'/60'/0'/0/0 for primary wallet, m/44'/60'/0'/1/{index} for payment addresses)
- **Key derivation**: PBKDF2 with 100,000 iterations using the Web Crypto API
- **Encryption**: AES-256-GCM with a unique 12-byte IV per encryption operation
- **Salt**: 16-byte cryptographically random salt per wallet
- **Storage model**: Server stores only the encrypted ciphertext (base64), salt, IV, and the derived public Ethereum address. The server never receives the user's password, plaintext mnemonic, or private keys.
- **Wallet export**: Compatible with MetaMask, Trust Wallet, and any BIP-39 compliant wallet
- **Auto-lock**: Configurable inactivity timeout (default 5 minutes, adjustable, or disabled entirely)
- **Implementation**: Web Crypto API (SubtleCrypto) for PBKDF2 and AES-256-GCM; viem library for Ethereum account derivation and transaction signing

### Transaction Signing
- All transaction signing occurs client-side using viem's `signTransaction`
- Server-mediated prepare → sign → broadcast architecture:
  1. Server prepares unsigned transaction (validates parameters, estimates gas, manages nonce)
  2. Client signs the transaction locally with the user's private key
  3. Client sends the signed transaction back to the server for broadcast
- Private keys never leave the browser at any point in this flow

### Authentication
- Two-step authentication: Email OTP verification followed by optional wallet connection
- Session-based with secure cookies
- Organization-scoped access control

---

## Smart Contracts

InvoCoin deploys auditable, Etherscan-verifiable smart contracts built entirely on battle-tested OpenZeppelin libraries. All contracts use Solidity 0.8.20+ with the following OpenZeppelin modules:

- **IERC20 + SafeERC20**: Safe ERC-20 token transfer operations (prevents silent transfer failures)
- **ReentrancyGuard**: Protection against reentrancy attacks on all payment functions
- **Pausable**: Emergency stop mechanism allowing contract operations to be paused
- **Ownable**: Administrative functions restricted to the contract owner

### SubscriptionAllowanceV2.sol
- **Purpose**: Manages recurring subscription payments with cap-based allowance system
- **Architecture**: Each organization deploys their own isolated contract instance (no shared state between organizations)
- **Key features**:
  - Subscribers approve specific puller addresses with a maximum spending cap
  - Gas sponsor (platform hot wallet) can execute payment pulls on behalf of approved pullers, enabling gasless subscription payments for end users
  - Multi-token support (USDC, USDT, DAI, and any ERC-20 token)
  - Pull tracking with running totals against approved caps
  - Allowance lifecycle management (register, update cap, cancel)
- **Events emitted**: AllowanceRegistered, PaymentPulled, AllowanceCancelled, AllowanceUpdated, OrganizationWalletUpdated, GasSponsorUpdated
- **Deployment**: Supports automated Etherscan verification (and chain-specific block explorers) for each supported network

### InvoicePaymentRouter.sol
- **Purpose**: Handles one-time invoice payments with gas sponsorship support
- **Architecture**: Organization-specific deployment with per-invoice payment authorization
- **Key features**:
  - Customer authorizes payment for a specific invoice ID
  - Platform gas sponsor can execute the payment pull (customer doesn't need native tokens for gas)
  - Funds route directly to the organization's wallet
  - Invoice ID tracking for automatic payment reconciliation
  - One-time payment model (each authorization can only be pulled once — prevents double-charging)
- **Security**: ReentrancyGuard on all payment functions, SafeERC20 for token transfers, Pausable for emergency stops

### Contract Verification
- Automated verification pipeline using Etherscan API (or equivalent block explorer API per network)
- Standard JSON input verification files maintained for reproducible builds
- Admin dashboard tracks deployment and verification status per chain

---

## Supported Blockchains

InvoCoin operates across 5 EVM-compatible networks:

| Network   | Native Token | Chain ID | Block Explorer           |
|-----------|-------------|----------|--------------------------|
| Ethereum  | ETH         | 1        | etherscan.io             |
| Polygon   | MATIC       | 137      | polygonscan.com          |
| Arbitrum  | ETH         | 42161    | arbiscan.io              |
| Optimism  | ETH         | 10       | optimistic.etherscan.io  |
| Base      | ETH         | 8453     | basescan.org             |

### Supported Stablecoins
- **USDC** (USD Coin) — Circle-issued, widely adopted across DeFi and CeFi
- **USDT** (Tether) — Largest stablecoin by market capitalization
- **DAI** (MakerDAO) — Decentralized, overcollateralized stablecoin

All stablecoin contract addresses are maintained in a verified coin registry with per-chain mappings.

---

## Platform Capabilities

### Invoice Management
- Professional invoice creation with line items, due dates, and custom branding
- Unique HD wallet-derived payment address per invoice (BIP-44 path derivation)
- Background payment detection with configurable blockchain polling intervals
- Partial payment support with automatic status transitions (pending → partially_paid → paid)
- QR code generation for easy mobile wallet scanning
- Customizable invoice templates

### Subscription Billing
- Recurring billing with automated payment collection via smart contracts
- Subscription lifecycle management (create, pause, resume, cancel, update)
- Tiered pricing support
- Coupon system with percentage or fixed-amount discounts, one-time / forever / limited-period durations
- Auto-pay via on-chain allowance contracts (no repeated manual approvals needed)

### Checkout Sessions
- Hosted checkout flows for one-time purchases, subscriptions, and multi-product bundles
- Embeddable checkout links for integration into existing websites
- Product catalog with quantity support

### Customer Management
- Customer directory with contact information and payment history
- Tax ID tracking and exemption management
- Per-customer billing preferences

### Tax Calculation
- Configurable tax profiles with country-specific rates
- Supported tax types: VAT, GST, Sales Tax
- Automatic reverse charge detection for EU B2B cross-border transactions
- Customer-level tax exemptions with certificate tracking
- Per-line-item tax breakdown with inclusive/exclusive calculation

### Dunning System
- Automated overdue invoice reminder sequences
- Configurable reminder intervals (e.g., 3, 7, 14 days after due date)
- Email notifications with merge fields for personalization

### Outbound Transfers (Send Crypto)
- Send stablecoins from the organization's HD wallet to any Ethereum address
- Server-side balance checks and gas estimation via Alchemy RPC
- Hot wallet gas sponsorship: platform sends native tokens to cover gas fees when user's wallet has insufficient balance
- Transaction status tracking with automatic confirmation detection

### Report Builder
- Custom report creation with multi-source data joins
- Data sources: Invoices, Customers, Products, Subscriptions, Auto-Pay Transactions
- Filtering, aggregation, sorting, and pagination

---

## Developer Platform

### Public REST API (v1)
- **Base URL**: https://invocoin.xyz/api/v1/
- **Authentication**: API key-based with SHA-256 hashing and environment-based prefixes (`inv_live_` for production, `inv_test_` for testing)
- **Permissions**: Two-tier model — `read_only` (GET only) and `full_access` (all operations)
- **Rate limiting**: Configurable from 10 to 10,000 requests per minute with sliding window algorithm
- **Caching**: In-memory validated key cache to reduce database load
- **Versioning**: Versioned routes (/api/v1/) for backward-compatible API evolution

Available API resources:
- Checkout sessions (create, retrieve)
- Invoices (create, list, retrieve, update)
- Customers (create, list, retrieve, update, delete)
- Subscriptions (create, list, retrieve, update, cancel)
- Products (create, list, retrieve, update)
- Agent-to-agent payments (initiate, confirm, status)

### Agent-to-Agent Payments (Agentic AI)

InvoCoin provides a headless, API-first payment flow designed for machine-to-machine transactions in the agentic AI world. AI agents can pay each other autonomously using stablecoins — no passwords, no checkout pages, no human intervention.

- **Documentation**: https://invocoin.xyz/docs/agent-payments
- **Use cases**: Agent marketplaces, usage-based AI billing, autonomous subscriptions, multi-agent workflows, compute/data purchasing, cross-border agent commerce
- **Authentication model**: ECDSA signature-based wallet verification. Sender agents prove wallet ownership by signing a message with their private key. The server recovers the wallet address from the signature — no accounts, passwords, or OAuth tokens needed for senders.

#### How It Works (Step by Step)

1. **Platform operator** creates an InvoCoin account and generates an API key with `full_access` permissions.
2. **Sender agent** calls `POST /api/v1/pay` with payment details (amount, currency, chain, senderAddress, line items). `recipientAddress` is optional — if omitted, payments go to the API key owner's organization wallet. InvoCoin creates an invoice and returns a `messageToSign`.
3. **Sender agent** signs the `messageToSign` with their wallet's private key (standard ECDSA signing, same as Ethereum transactions).
4. **Sender agent** sends the stablecoin transfer on-chain (standard ERC-20 transfer) and obtains a transaction hash.
5. **Sender agent** calls `POST /api/v1/pay/:sessionId/confirm` with the signature and transaction hash. InvoCoin verifies the signature via ECDSA recovery, records the payment, marks the invoice as paid.
6. **Recipient** receives webhook notifications (`payment.received`, `invoice.paid`) and can trigger downstream actions.

#### API Endpoints

- `POST /api/v1/pay` — Initiate a payment. Requires: amount (cents), currency (USDC/USDT/DAI), chain (ethereum/polygon/arbitrum/optimism/base), senderAddress, lineItems array, customer object. Optional: recipientAddress (defaults to your organization's wallet if omitted). Returns: sessionId, invoiceId, messageToSign, expiresAt (30 min TTL).
- `POST /api/v1/pay/:sessionId/confirm` — Confirm payment with ECDSA signature and on-chain txHash. Returns: status (completed), paymentId.
- `GET /api/v1/pay/:sessionId` — Poll payment status. Returns: session details, linked invoice, recorded payments.

#### Quick Example (Node.js with viem)

```javascript
import { privateKeyToAccount } from 'viem/accounts';

const API_KEY = 'inv_live_YOUR_API_KEY';
const account = privateKeyToAccount('0xYOUR_PRIVATE_KEY');

// 1. Initiate payment
const init = await fetch('https://invocoin.xyz/api/v1/pay', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    amount: 5000, currency: 'USDC', chain: 'polygon',
    senderAddress: account.address,
    lineItems: [{ description: 'Translation service', quantity: 1, unitPrice: 5000 }],
    customer: { name: 'Agent A' }
  })
});
const { data } = await init.json();

// 2. Sign the message
const signature = await account.signMessage({ message: data.messageToSign });

// 3. Send USDC on-chain, get txHash
const txHash = '0x...'; // Your on-chain transfer

// 4. Confirm
await fetch(`https://invocoin.xyz/api/v1/pay/${data.sessionId}/confirm`, {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ signature, txHash })
});
```

#### Supported Configurations

| Network   | Chain ID | Currency Options     |
|-----------|----------|---------------------|
| Ethereum  | 1        | USDC, USDT, DAI     |
| Polygon   | 137      | USDC, USDT, DAI     |
| Arbitrum  | 42161    | USDC, USDT, DAI     |
| Optimism  | 10       | USDC, USDT, DAI     |
| Base      | 8453     | USDC, USDT, DAI     |

All amounts are in cents (e.g., 5000 = $50.00 USD). Payment sessions expire after 30 minutes.

### Webhook System
- **15 event types** across 5 categories for real-time notifications:
  - **Invoice**: invoice.created, invoice.paid, invoice.overdue
  - **Checkout**: checkout_session.completed
  - **Subscription**: subscription.created, subscription.renewed, subscription.cancelled, subscription.paused, subscription.resumed, subscription.updated
  - **Payment**: payment.received, payment.confirmed
  - **Customer**: customer.created, customer.updated, customer.deleted
- **Security**: HMAC-SHA256 request signatures (`X-InvoCoin-Signature` header), timestamp verification (`X-InvoCoin-Timestamp`), event type header (`X-InvoCoin-Event`)
- **Reliability**: Up to 4 retry attempts with exponential backoff (immediate, 1min, 5min, 25min), 10-second timeout per attempt
- **Auto-disable**: Endpoints automatically disabled after 5 consecutive delivery failures
- **Pattern**: Fire-and-forget — webhook failures never block main API responses
- **Management**: Full CRUD for webhook endpoints, event selection, delivery logs, test delivery, and secret rotation

---

## Technical Stack

| Layer          | Technology                                          |
|----------------|-----------------------------------------------------|
| Frontend       | React 18, TypeScript, Tailwind CSS, shadcn/ui       |
| Backend        | Node.js, Express                                    |
| Database       | PostgreSQL with Drizzle ORM                         |
| Validation     | Zod schemas (shared between frontend and backend)   |
| Web3 Client    | Wagmi v2 (wallet connections), viem (transactions)  |
| Wallet Connect | WalletConnect protocol                              |
| Blockchain RPC | Alchemy (reliable node infrastructure)              |
| Smart Contracts| Solidity 0.8.20+, OpenZeppelin Contracts            |
| Email          | Nodemailer (transactional emails, OTP, reminders)   |
| Icons          | Lucide React, React Icons                           |

---

## Content & Resources

### Documentation
- **Quick Start Guide**: https://invocoin.xyz/docs/quick-start
- **HD Wallet Technical Deep-Dive**: https://invocoin.xyz/docs/hd-wallet
- **Smart Contracts Documentation**: https://invocoin.xyz/docs/smart-contracts
- **Webhook Integration Guide**: https://invocoin.xyz/docs/webhooks
- **Agent-to-Agent Payments Guide**: https://invocoin.xyz/docs/agent-payments
- **API Reference**: https://invocoin.xyz/docs/api-reference

### Educational Guides
- What Are Stablecoins: https://invocoin.xyz/guides/what-are-stablecoins
- How Crypto Wallets Work: https://invocoin.xyz/guides/how-crypto-wallets-work
- Understanding Blockchain Networks: https://invocoin.xyz/guides/understanding-blockchain-networks
- Crypto Security Best Practices: https://invocoin.xyz/guides/crypto-security-best-practices
- How Smart Contracts Work: https://invocoin.xyz/guides/how-smart-contracts-work
- How Crypto Payments Work: https://invocoin.xyz/guides/how-crypto-payments-work

### Blog
- Beyond Bitcoin: 5 Surprising Truths About How Stablecoins Are Quietly Rebuilding Business Finance: https://invocoin.xyz/blog/stablecoins-business-finance
- 5 Surprising Truths About the Real Stablecoin Revolution: https://invocoin.xyz/blog/stablecoin-revolution
- Smart Contracts Explained: https://invocoin.xyz/blog/smart-contracts-explained

### Competitor Comparisons
- Compare InvoCoin: https://invocoin.xyz/compare
- InvoCoin vs BitPay: https://invocoin.xyz/compare/invocoin-vs-bitpay
- InvoCoin vs CoinPayments: https://invocoin.xyz/compare/invocoin-vs-coinpayments
- InvoCoin vs Coinbase Commerce: https://invocoin.xyz/compare/invocoin-vs-coinbase-commerce
- InvoCoin vs Copperx: https://invocoin.xyz/compare/invocoin-vs-copperx
- InvoCoin vs Helio: https://invocoin.xyz/compare/invocoin-vs-helio
- InvoCoin vs Loop Crypto: https://invocoin.xyz/compare/invocoin-vs-loop-crypto
- InvoCoin vs BoomFi: https://invocoin.xyz/compare/invocoin-vs-boomfi
- InvoCoin vs Radom: https://invocoin.xyz/compare/invocoin-vs-radom

### Additional Pages
- Features Overview: https://invocoin.xyz/features
- Pricing: https://invocoin.xyz/pricing
- FAQ: https://invocoin.xyz/faq
- Resources: https://invocoin.xyz/resources

---

## Trust Signals

- **Non-custodial architecture**: Users control their own private keys; the platform cannot access or move user funds
- **Industry-standard cryptography**: BIP-39, BIP-44, PBKDF2 (100k iterations), AES-256-GCM — all well-established, peer-reviewed standards
- **OpenZeppelin smart contracts**: Built on the most widely audited and trusted Solidity library in the Ethereum ecosystem
- **On-chain verifiable**: Smart contracts support Etherscan verification, making source code publicly readable and auditable
- **No token, no ICO**: InvoCoin is a payment infrastructure platform — it does not issue its own cryptocurrency token
- **Stablecoin-focused**: Transactions use established, regulated stablecoins (USDC, USDT, DAI), not volatile cryptocurrencies
- **Transparent security model**: Full documentation of the encryption pipeline, key derivation, and signing architecture is publicly available
- **Standard Web3 tooling**: Built with Wagmi, viem, WalletConnect, and Alchemy — the same tools used by major DeFi protocols
- **Multi-chain deployment**: Operates on established, high-security L1 and L2 networks (Ethereum, Polygon, Arbitrum, Optimism, Base)

---

## Legal

- **Terms of Service**: https://invocoin.xyz/terms
- **Privacy Policy**: https://invocoin.xyz/privacy
- **Refund & Cancellation Policy**: https://invocoin.xyz/refund-policy
- **Legal contact**: communications@invocoin.xyz

---

## Contact

For more information about accepting stablecoin payments for your business, visit https://invocoin.xyz