# Nicky

> Nicky is a cryptocurrency payment platform that lets individuals and businesses receive crypto payments through a personal payment link. Every user gets a public profile (e.g. `https://pay.nicky.me/s/ABCDE`) and can generate payment requests (e.g. `https://pay.nicky.me/payment-report/ABCDE?paymentId=VWXYZ`) for specific amounts in any supported asset. Anyone — including AI agents — can discover and pay a request without signing up. Nicky handles multi-asset acceptance, real-time conversion, on-chain monitoring, and optional fiat off-ramp in a single flow.

## Platform Overview

**What Nicky does:**
Nicky gives every user a short, shareable payment link tied to their profile short ID. A receiver sets up which crypto assets they accept; a payer visits the link, picks an asset, and sends to a generated wallet address. Nicky monitors the blockchain, matches the incoming transaction, applies any conversion, and credits the receiver — all without requiring the payer to create an account.

**Key concepts:**
- **Profile short ID** — a user's short identifier (e.g. `ABCDE`). Resolves to `https://pay.nicky.me/s/ABCDE` (or by email `https://pay.nicky.me/e/EMAIL`, or by domain `https://pay.nicky.me/d/DOMAIN`).
- **Payment request** — a specific ask for an amount and asset (e.g. "Pay me 50 USDT"). Has a 6-character short ID. The canonical URL is `https://pay.nicky.me/payment-report/ABCDE?paymentId=VWXYZ` (receiver's short ID + payment request / bill short ID).
- **Payment attempt** — a payer's attempt to fulfil a request. Tracks the wallet address used, amount sent, transaction hash, and confirmation status. Identified by a 6-character short ID returned by `start-payment`.
- **Asset** — a blockchain asset the platform supports (e.g. `USDT_TRC20`, `ETH.ETH`, `BTC.BTC`).
- **Wallet route / connection** — a receiver's configured wallet address for a given asset.
- **Conversion** — if the payer pays in a different asset than requested, Nicky fetches a live rate and converts automatically.

**Supported assets:**
- Bitcoin: `BTC.BTC`
- Ethereum: `ETH.ETH`, `ETH.USDT`, `ETH.USDC`
- Tron: `USDT_TRC20` (TRC-20 USDT), `TRX`
- Polygon: `MATIC.POL`, `MATIC.USDT`, `MATIC.USDC`

**Supported fiat currencies (for request denomination):** USD, EUR, GBP, BRL, DKK, SEK, NOK, CHF, CAD, AUD, NZD, HKD, SGD, ZAR, JPY, CNY, KRW, AED, TRY, PLN, HUF, CZK, RON, RUB, ARS, CLP, COP, PEN, UYU, BOB, and 10+ more.

**Languages:** English, Spanish, Portuguese (BR), Italian, French, Greek, Russian, Arabic, Chinese (Simplified), Danish, Hebrew, Dutch.

**Payment window:** 30 minutes from calling `start-payment`. Calling `start-payment` again with the same payer + request + asset is idempotent (returns same address and amount).

**Authentication:**
- Users authenticate via Auth0 (passwordless email or social login).
- The API supports Auth0 JWT tokens and API keys (`X-Api-Key` header).
- All agent/public payment endpoints are anonymous — no account or key required.

## URL Format Reference

When linking to Nicky, use these canonical formats:

- **Profile (by short ID):** `https://pay.nicky.me/s/ABCDE` where `ABCDE` is the user's short ID.
- **Profile (by email):** `https://pay.nicky.me/e/EMAIL`
- **Profile (by domain):** `https://pay.nicky.me/d/DOMAIN`
- **Payment request:** `https://pay.nicky.me/payment-report/ABCDE?paymentId=VWXYZ` where `ABCDE` is the receiver's short ID and `VWXYZ` is the payment request / bill short ID.

## Payment Processing Pipeline

Once a payer sends funds, Nicky's backend processes the transaction through a sequence of background services. This pipeline runs continuously and is fully automatic.

**Processing stages (in order):**

| Stage | Service | Interval | What it does |
|---|---|---|---|
| 1 | Deposit discovery | 30 s | Polls exchange connectors for new deposits; processes payer-submitted tx hashes |
| 2 | Ambiguity detection | 24 s | Detects when multiple payers use the same address; emails payer to submit tx hash |
| 3 | Blockchain validation | 60 s | Verifies tx on-chain; requires **10+ confirmations**; records token transfers |
| 4 | Transaction matching | 35 s | Matches deposit to the payer's address lease (30-min window, ±2% amount tolerance) |
| 5 | Report creation | 45 s | Creates the merchant-facing payment report and links it to the invoice |
| 6 | Finalization | 61 s | IP/fraud/blacklist checks; validates conversion quote; sends confirmation emails |
| 7–10 | Fiat conversion & off-ramp | 35–120 s each | (Optional) Converts crypto→fiat via exchange and triggers bank withdrawal |

**Typical confirmation times:**
- TRC-20 / Polygon: **3–8 minutes** (2–3 s block time, 10 confirmations)
- Ethereum: **5–15 minutes** (15 s block time)
- Bitcoin: **60–120 minutes** (10 min blocks, 10 confirmations)

**To speed up confirmation:** submit the tx hash via `POST /api/agents/payment/report-transaction` immediately after the on-chain send.

**Address lease:** each payment session uses a unique wallet address valid for **30 minutes**. Funds sent after expiry may not be automatically matched to the payment request.

**Amount tolerance:** deposits are matched with **±2%** tolerance. Sending the exact quoted amount is strongly recommended.

## AI Agent Integration

Nicky is fully accessible to AI agents via REST and MCP. No authentication is required for the payment flow.

**Typical agent flow:**
1. Resolve the short ID from a message like "Pay request #ABCDEF" or a `pay.nicky.me/payment-report/ABCDE?paymentId=VWXYZ` link.
2. `GET /api/agents/payment-request?shortId=ABCDEF` — discover receiver, open amount, accepted assets.
3. Collect payer name and email from the user (required so the receiver can identify who paid).
4. `POST /api/agents/payment/start` — choose an asset, submit payer info, receive wallet address + exact amount.
5. Send the on-chain payment (or instruct the user to send it).
6. *(Optional)* `POST /api/agents/payment/report-transaction` — submit the TX hash for faster verification.
7. `GET /api/agents/payment/progress?paymentAttemptId=X7K2P1` — poll every 15–30 s until `status == "Confirmed"` or `isPaid == true`.

**MCP server (Model Context Protocol):**
- Public (anonymous): `https://api-public.pay.nicky.me/mcp-public/`
  Tools: `GetPaymentRequest`, `StartPayment`, `ReportTransaction`, `GetPaymentProgress`
- Private (API key via `X-Api-Key`): `https://api-public.pay.nicky.me/mcp/`
  Tools: account & nick management, balance inquiries, billing, credit transfers, payment request management, payment reports, user asset connections, webhooks, conversion rates, address management, accepted assets, and all public tools above.

## Docs

- [Agent integration guide](https://api-public.pay.nicky.me/agents.md): Complete step-by-step instructions for AI agents to discover and pay Nicky payment requests. Covers the full REST flow, MCP details, status values, and conversion notes.
- [OpenAPI spec – Agents API](https://api-public.pay.nicky.me/openapi/agents.json): Machine-readable OpenAPI specification for all anonymous agent endpoints.
- [Interactive API docs](https://api-public.pay.nicky.me/scalar): Scalar-powered interactive documentation. Select "Nicky Agents API" in the top-right for the agent-focused view.

## Discovery

- [MCP server – public](https://api-public.pay.nicky.me/mcp-public/): Anonymous MCP endpoint — tools: GetPaymentRequest, StartPayment, ReportTransaction, GetPaymentProgress. No auth required.
- [MCP server – private](https://api-public.pay.nicky.me/mcp/): Authenticated MCP endpoint (X-Api-Key header) — all public tools plus account management, balances, billing, payment requests, payment reports, webhooks, and more.
- [Agent integration guide](https://api-public.pay.nicky.me/agents.md): Step-by-step guide for AI agents to discover and pay Nicky payment requests.
- [MCP server card](https://api-public.pay.nicky.me/.well-known/mcp/server-card.json): JSON-LD description of the MCP server, transport, auth, and tools.

## Bot-Specific Resources

- [Crypto exchange & rate bots](https://pay.nicky.me/llms-bestchange.txt): Asset identifiers, exchange pairs, rate mechanics, and API endpoints for exchange-rate aggregators (BestChange)
- [Crypto exchange link-preview fetchers](https://pay.nicky.me/llms-bestchange-bot.txt): Page metadata and preview context for BestChange Bot
- [Creator & music payment bots](https://pay.nicky.me/llms-hifibot.txt): Crypto payment flows for musicians, creators, and freelancers (HIFIBot / HIFI)
- [E-commerce crawlers](https://pay.nicky.me/llms-storebot-google.txt): Checkout flow, payment methods, merchant fees, webhooks, and fulfilment data (Storebot-Google)

## Optional

- [OpenAPI spec – Full Public API](https://api-public.pay.nicky.me/openapi/v1.json): Full OpenAPI spec covering all authenticated public API endpoints (requires API key).
- [Nicky homepage](https://nicky.me): Marketing site with product information, pricing, and sign-up.
- [Pay portal](https://pay.nicky.me): The main payment application. Visit `pay.nicky.me/s/ABCDE` to pay a user, or `pay.nicky.me/payment-report/ABCDE?paymentId=VWXYZ` to pay a specific request.
- [WordPress site GEO files](https://nicky.me/llms.txt): LLM/GEO reference files for the nicky.me marketing site.