---
name: algovoi
description: Use when building payment infrastructure for agents, e-commerce
  stores, APIs, or chat bots that need to accept stablecoin payments with
  compliance screening. Reach for this skill when you need to create payment
  links, verify transactions, integrate with x402/MPP/AP2/A2A protocols, handle
  webhooks, or manage multi-chain settlement across Algorand, VOI, Hedera,
  Stellar, Base, Solana, and Tempo.
metadata:
  mintlify-proj: algovoi
  version: "1.0"
---

# AlgoVoi Skill

## Product summary

AlgoVoi is a compliance-aware payment gateway for stablecoin transactions across seven blockchains (Algorand, VOI, Hedera, Stellar, Base, Solana, Tempo). It handles settlement, sanctions screening, KYB gating, and audit-chain recording on every payment. The gateway sits at `https://api.algovoi.co.uk` and supports four agentic payment protocols: x402 (per-request API monetisation), MPP (MCP tool pricing), AP2 (Google mandate-based commerce), and A2A (agent-to-agent settlement). All payments settle directly to your on-chain wallet—AlgoVoi never holds funds. Use the dashboard at `dash.algovoi.co.uk` to manage tenants, API keys, payout addresses, and webhooks. Native SDKs (Go, PHP, Python, Rust) and framework adapters (Shopify, Discord, LangChain, etc.) are available at [github.com/chopmob-cloud/AlgoVoi-Platform-Adapters](https://github.com/chopmob-cloud/AlgoVoi-Platform-Adapters).

## When to use

Reach for AlgoVoi when:

- **Building agent payment infrastructure**: Agents need to pay for API calls, MCP tools, or other agents' capabilities with cryptographic proof of settlement.
- **Creating payment links**: You need a quick hosted checkout for customers to pay in stablecoin without building a wallet integration.
- **Gating HTTP endpoints**: Protect APIs with x402 (HTTP 402 Payment Required) and charge per request.
- **Handling recurring payments**: Implement subscription or mandate-based billing with AP2 or MPP.
- **Integrating with e-commerce**: Drop-in adapters exist for Shopify, WooCommerce, BigCommerce, and 20+ platforms.
- **Running chat-bot payments**: Accept payments inside Discord, Telegram, X, or Viber.
- **Needing compliance evidence**: You must screen payers against sanctions lists, maintain audit chains, or produce signed receipts for regulatory review.
- **Multi-chain settlement**: Your customers hold USDC on different chains and you want one integration.

Do not use AlgoVoi for: fiat-only payments, custody-based wallets, or platforms that don't need on-chain settlement.

## Quick reference

### API endpoints and authentication

| Task | Endpoint | Headers |
| --- | --- | --- |
| Create payment link | `POST /v1/payment-links` | `Authorization: Bearer <API_KEY>`, `X-Tenant-Id: <TENANT_ID>` |
| Check payment status | `GET /v1/payment-links/{token}` | Same auth headers |
| x402 requirements | `POST /v1/x402/requirements` | Same auth headers |
| x402 verify | `POST /v1/x402/verify` | Same auth headers |
| Compliance screen | `GET /v1/compliance/screen?address=<addr>` | Public endpoint (no auth) |
| Compliance attestation | `GET /v1/compliance/attestation` | Public endpoint (no auth) |

### Key types and prefixes

| Prefix | Purpose | Where to use |
| --- | --- | --- |
| `algv_…` | Tenant-scoped API key | Backend API calls, payment creation |
| `algvc_…` | Admin/control-plane key | Operator-only, multi-tenant management |
| `algvw_…` | Webhook signing secret | Verify inbound webhook signatures |

### Rate limits

- **Per-tenant**: 300 requests/minute (burst 60)
- **Per-IP**: 120 requests/minute (burst 30) for unauthenticated endpoints
- **Per-checkout**: 60 requests/minute for polling status

Response headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`. On 429, respect the `Retry-After` header and use exponential backoff with jitter.

### Webhook verification

All webhooks carry `X-AlgoVoi-Signature: t={unix_ts},v1={hex}` header. Verify by:

1. Parse `t` and `v1` from header
2. Reject if `abs(now - t) > 300` (5-minute tolerance)
3. Compute `HMAC-SHA256(secret, "{t}.{raw_body}")`
4. Compare result with `v1` in constant time

Deduplicate on the `id` field—events may be redelivered.

### Supported chains and assets

| Chain | Native | Stablecoin | CAIP-2 |
| --- | --- | --- | --- |
| Algorand mainnet | ALGO | USDC (ASA 31566704) | `algorand:mainnet` |
| VOI mainnet | VOI | aUSDC (ARC-200) | `voi:mainnet` |
| Hedera mainnet | HBAR | USDC (HTS) | `hedera:mainnet` |
| Stellar mainnet | XLM | USDC | `stellar:mainnet` |
| Base mainnet | ETH | USDC (ERC-20) | `eip155:8453` |
| Solana mainnet | SOL | USDC (SPL) | `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp` |
| Tempo mainnet | ETH | USDCe (TIP-20) | `tempo:mainnet` |

## Decision guidance

### When to use each payment protocol

| Protocol | Use case | Best for | Settlement |
| --- | --- | --- | --- |
| **x402** | Per-request API monetisation | LLM calls, data lookups, microservices | Direct on-chain |
| **MPP** | MCP tool pricing | Claude Desktop, Cursor, Windsurf tools | Direct on-chain |
| **AP2** | Mandate-based agent commerce | Agent proposes, human approves once, agent executes | Direct on-chain |
| **A2A** | Agent-to-agent settlement | Agents paying other agents autonomously | Direct on-chain |
| **Hosted checkout** | Simple one-off payments | E-commerce, donations, quick demos | Direct on-chain |

### When to use test vs. live mode

| Mode | When | Limits | KYC required |
| --- | --- | --- | --- |
| **Test** | Development, demos, learning | 60 days free testnet | No |
| **Live** | Production payments | $1,000 free mainnet (after KYC), then 0.50% take rate | Yes |

Keys are mode-bound. Create separate keys for test and live.

### When to use native SDK vs. REST API

| Approach | When | Pros | Cons |
| --- | --- | --- | --- |
| **Native SDK** | No framework adapter exists, cold-start budget matters | Single file, no dependencies, standard library only | Limited to three methods (create, verify, status) |
| **REST API** | Full control, custom workflows | Complete endpoint coverage | Must handle auth, rate limits, retries yourself |
| **Framework adapter** | Your platform is listed (Shopify, Discord, etc.) | Pre-built, compliance gating automatic | Locked to that platform |

## Workflow

### 1. Create a tenant and get API keys

1. Sign up at `dash.algovoi.co.uk/signup`
2. You get 60 days of free testnet immediately
3. Go to **Settings → API keys** and create a new key (test mode)
4. Copy the key once—it's never shown again
5. Note your **Tenant ID** from **Settings**

### 2. Configure a payout address

1. In the dashboard, go to **Settings → Networks**
2. Pick a chain (Algorand testnet is fastest to demo)
3. Paste a wallet address you control
4. This is where settled payments land (non-custodial)

### 3. Create a payment link (hosted checkout)

```bash
curl -X POST https://api.algovoi.co.uk/v1/payment-links \
  -H "Authorization: Bearer $ALGOVOI_API_KEY" \
  -H "X-Tenant-Id: $TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1.00,
    "currency": "USD",
    "label": "Order #1234",
    "preferred_network": "algorand_testnet"
  }'
```

You get back a `checkout_url`. Open it in a browser—customer sees a QR code and memo to include.

### 4. Verify the payment

After the customer pays on-chain, poll the status:

```bash
curl -X GET https://api.algovoi.co.uk/v1/payment-links/$TOKEN \
  -H "Authorization: Bearer $ALGOVOI_API_KEY" \
  -H "X-Tenant-Id: $TENANT_ID"
```

Response: `{ "status": "paid", "tx_id": "...", "amount_microunits": "1000000" }`

### 5. Receive and verify webhooks

1. In **Settings → Notifications**, add a webhook destination (HTTPS URL)
2. You get a per-destination signing secret
3. When a payment confirms, AlgoVoi POSTs a Stripe-shaped event
4. Verify the signature using the secret and the `X-AlgoVoi-Signature` header
5. Deduplicate on the `id` field (events may be redelivered)

### 6. Go live

1. Complete KYC in the dashboard
2. Create a new API key in **live mode**
3. Update your payout addresses for mainnet chains
4. Redeploy with the live key
5. You get $1,000 free mainnet allowance; after that, 0.50% take rate

## Common gotchas

- **Forgetting the X-Tenant-Id header**: Every authenticated request needs both `Authorization` and `X-Tenant-Id`. Missing either returns 401 or 403.
- **Reusing API keys across test and live**: Keys are mode-bound. Create separate keys for each mode. A test key cannot call mainnet.
- **Not deduplicating webhooks**: AlgoVoi guarantees at-least-once delivery. Implement persistent deduplication on the `id` field (Redis SET, database unique index).
- **Ignoring the 5-minute webhook timestamp tolerance**: Reject webhooks with `abs(now - t) > 300`. This prevents replay attacks.
- **Trying to verify a payment without waiting for finality**: On-chain finality varies by chain (5 seconds on Algorand, 12 seconds on Solana). Poll the status endpoint or wait for the webhook.
- **Sending the same Idempotency-Key with different payloads**: If you retry with the same key but different request body, you get 422 Unprocessable Entity. Use the same key only for identical requests.
- **Configuring a payout address you don't control**: Funds go directly to this address. If you paste the wrong address, you lose the payment.
- **Not handling 402 Payment Required responses**: x402 endpoints return 402 with a `payment_requirements` body. This is not an error—it's the start of the payment flow. Parse it and present the payment options to the client.
- **Hitting rate limits without backoff**: When you get 429, respect the `Retry-After` header. Use exponential backoff with jitter to avoid thundering herd.
- **Assuming compliance screening is automatic**: Call `/compliance/screen` before your agent pays. The gateway screens on every payment, but agents should pre-screen recipients to avoid failed transactions.

## Verification checklist

Before deploying to production:

- [ ] API key is in live mode and stored securely (environment variable, secrets manager)
- [ ] Tenant ID is correct and matches the key
- [ ] Payout address is configured for every chain you plan to use
- [ ] Payout address is a wallet you control (test by sending a small amount)
- [ ] Webhook destination is HTTPS and publicly reachable
- [ ] Webhook signature verification is implemented (test with a curl replay)
- [ ] Idempotency-Key is sent on all POST requests that create resources
- [ ] Webhook deduplication is implemented (check `id` field)
- [ ] Rate-limit handling is in place (exponential backoff on 429)
- [ ] Error handling covers 4xx (caller fix) vs. 5xx (retry) cases
- [ ] KYC is complete and `kyb_status = approved` in the dashboard
- [ ] You've tested a full payment flow on testnet before going live
- [ ] Compliance screening is called before agents pay (if using agents)

## Resources

- **Comprehensive navigation**: [https://docs.algovoi.co.uk/llms.txt](https://docs.algovoi.co.uk/llms.txt) — page-by-page index of all documentation
- **Quickstart**: [https://docs.algovoi.co.uk/quickstart](https://docs.algovoi.co.uk/quickstart) — five-minute walkthrough of your first payment
- **API reference**: [https://docs.algovoi.co.uk/api-reference/introduction](https://docs.algovoi.co.uk/api-reference/introduction) — base URL, authentication, versioning, rate limits
- **Integrations**: [https://docs.algovoi.co.uk/integrations/overview](https://docs.algovoi.co.uk/integrations/overview) — framework adapters, SDKs, chat bots, e-commerce
- **Compliance**: [https://docs.algovoi.co.uk/compliance](https://docs.algovoi.co.uk/compliance) — screening sources, audit chain, regulatory frameworks
- **Support**: [https://docs.algovoi.co.uk/support](https://docs.algovoi.co.uk/support) — how to reach the team, what to include in bug reports

---

> For additional documentation and navigation, see: https://docs.algovoi.co.uk/llms.txt