back
loading skill details...
Discover and pay Nicky cryptocurrency payment requests on behalf of users. Covers payment request lookup, asset selection, wallet address generation, transac...
---
name: nicky-payments
description: Discover and pay Nicky cryptocurrency payment requests on behalf of users. Covers payment request lookup, asset selection, wallet address generation, transaction reporting, and confirmation polling via REST API and MCP — no authentication required for the payment flow.
version: 1.1.0
metadata:
openclaw:
primaryEnv: NICKY_API_KEY
envVars:
- name: NICKY_API_KEY
required: false
description: Optional API key for the private Nicky MCP endpoint (account management, balances, billing, payment requests, payment reports, webhooks, credit transfers). Not required for the anonymous public payment flow used by this skill.
emoji: "💸"
homepage: https://pay.nicky.me
---
# Nicky Payments
Pay Nicky cryptocurrency payment requests on behalf of a user, end to end.
Nicky is a crypto payment platform where a receiver creates a short payment link
(`https://pay.nicky.me/s/ABCDE` for their profile, or
`https://pay.nicky.me/payment-report/ABCDE?paymentId=VWXYZ` for a specific request). Anyone —
including an AI agent — can discover the request, receive a wallet address, and send funds. Nicky
handles on-chain monitoring, asset conversion, and confirmation.
## URL Formats
When sharing a Nicky link with a user, use these canonical formats:
- **Profile:** `https://pay.nicky.me/s/ABCDE` where `ABCDE` is the user's short ID
- **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
## When to use this skill
Use this skill when the user asks to:
- Pay a Nicky request: "Pay `pay.nicky.me/payment-report/ABCDE?paymentId=VWXYZ`" or "Pay request #VWXYZ"
- Send crypto to a Nicky payment link shared in chat
- Check whether a Nicky payment attempt has been confirmed
- Report a blockchain transaction hash to speed up a pending Nicky payment
- Look up the assets a Nicky receiver accepts
If the user only wants to *receive* crypto on Nicky, do not use this skill — direct them to
<https://pay.nicky.me> to sign up.
## Quick start
The full payment flow runs without authentication. The agent drives the user-facing
conversation; the API does the rest.
1. **Resolve the short ID** from the message or URL. Accepted forms:
- `pay.nicky.me/payment-report/ABCDE?paymentId=VWXYZ` → `shortId = "VWXYZ"` (use the `paymentId` value)
- `#VWXYZ` → `shortId = "VWXYZ"`
- `pay.nicky.me/s/ABCDE` (profile) → no payment request; direct the user to a specific request first
2. **Discover the request** — see [REST API → Get payment request](./references/api.md#get-payment-request).
Returned payload includes the receiver (`receiverUser`), `description`, `invoiceReference`,
`totalAmount`, `openAmount`, `nativeAssetId`, `status`, and the list of `availableAssets`.
3. **Ask the user** for `payerName` and `payerEmail` (the receiver uses these to identify who
paid). Never invent them.
4. **Pick an asset** — prefer the native asset of the request; otherwise pick one the receiver
accepts and let Nicky convert (the exact converted amount is returned by `start-payment`).
5. **Start the payment** — see [REST API → Start payment](./references/api.md#start-payment).
Capture `paymentAttemptId`, `walletAddress`, `amountToSend`, `assetId`, `memo` (if present),
`paymentRequestShortId`, and `expiresAt`. The address lease is valid for **30 minutes**.
6. **Instruct the user (or the agent's own wallet) to send** the exact `amountToSend` of the chosen
asset to `walletAddress` before `expiresAt`. If the exact amount is impractical (e.g. gas),
warn that the deposit is matched with **±2%** tolerance. If `memo` is non-null, include it.
7. **(Recommended) Report the tx hash** as soon as the transaction is broadcast — see
[REST API → Report transaction](./references/api.md#report-transaction). This skips
deposit polling and jumps straight to blockchain validation, which can save minutes.
8. **Poll for confirmation** every 15–30 s — see [REST API → Payment progress](./references/api.md#payment-progress).
Stop when `status == "Confirmed"` OR `isPaid == true`.
## Status values
`GET /payment/progress` returns one of:
| Status | Meaning | Agent action |
| ----------- | ---------------------------------------------------------------- | --------------------------------------------- |
| `Pending` | Waiting for the transaction to appear on-chain or in the queue | Keep polling (or wait for the report-tx call) |
| `Received` | Transaction detected, waiting for confirmations | Keep polling |
| `Confirmed` | Confirmed, matched to the request, and credited | Stop polling — report success to the user |
| `Expired` | 30-minute window closed before any matching deposit | Tell the user, offer to start a new attempt |
## Critical rules
These are the rules agents most often get wrong. Read them carefully.
- **Never invent payer details.** `payerName` and `payerEmail` are required and are shown to
the receiver. Always ask the user.
- **Send the exact quoted amount.** The `amountToSend` returned by `start-payment` is the amount
that will be matched. Sending more or less than ±2% risks the deposit being un-matched.
- **Honor the 30-minute window.** Funds sent after `expiresAt` may not auto-match. If the
window has expired, call `start-payment` again — it is **idempotent** for the same
payer + request + asset, so a fresh address will be issued and the prior attempt can be
abandoned.
- **Memo matters.** If the response includes a `memo` (destination tag for networks that need
one), pass it to the wallet or the funds may not be credited.
- **No API key is required** for the public payment flow. If the user supplies an API key
(`NICKY_API_KEY`) the private MCP endpoint exposes account, nick, balance, billing, credit,
payment-request, payment-report, and webhook tools — see [MCP reference](./references/mcp.md).
## MCP server (preferred for MCP-capable agents)
If the host supports MCP, prefer connecting to the public MCP endpoint — it exposes the same
tools as the REST flow and avoids hand-built HTTP calls.
- **Public MCP (no auth):** `https://api-public.pay.nicky.me/mcp-public/`
- Tools: `GetPaymentRequest`, `StartPayment`, `ReportTransaction`, `GetPaymentProgress`,
`SearchNicks`
- **Private MCP (`X-Api-Key: $NICKY_API_KEY`):** `https://api-public.pay.nicky.me/mcp/`
- All public tools plus `GetCurrentUser`, `UpdateCurrentUser`, `GetAllNicks`, `AddNicks`,
`GetBalances`, `GetAcceptedAssets`, `GetEnabledAssetConnections`, `GetDepositAddress`,
`GetConversionRate`, `GetUnusedConversionQuote`, `CreatePaymentRequest`, `GetPaymentRequests`,
`GetPaymentRequestById`, `GetPaymentRequestByShortId`, `CancelPaymentRequest`,
`FinishPaymentRequest`, `GetPaymentReports`, `GetPaymentReportById`,
`GetPaymentReportsByBillShortId`, `GetCreditBalance`, `GetCreditBalanceForSubAccount`,
`ListCreditTransfers`, `TransferCredits`, `GetBillingGroups`, `ListSubAccounts`,
`UnlinkSubAccount`, `CreateSubAccount`, `CreateWebHook`, `ListWebHooks`, `DeleteWebHook`, `Echo`
- **Server card:** <https://api-public.pay.nicky.me/.well-known/mcp/server-card.json>
See [MCP reference](./references/mcp.md) for tool signatures.
## Payment processing pipeline (for setting expectations)
After a payer sends funds, Nicky's backend runs a sequence of background workers to discover,
validate, match, and finalize the payment.
| Stage | What happens | Polling interval |
|---|---|---|
| Deposit discovery | Exchange connector polled for new deposits | every 30 s |
| Blockchain validation | On-chain tx verified; **10+ confirmations required** | every 60 s |
| Transaction matching | Deposit matched to the payer's 30-minute address lease (±2% amount tolerance) | every 35 s |
| Payment report creation | Report linked to the payment request | every 45 s |
| Finalization | Fraud/blacklist checks, quote validation, confirmation email sent | every 61 s |
**Typical end-to-end confirmation time:**
- TRC-20 / Polygon: **3–8 minutes**
- Ethereum: **5–15 minutes**
- Bitcoin: **60–120 minutes**
**Speed up confirmation:** submit the tx hash via `report-transaction` immediately after
broadcasting. This skips deposit polling and jumps straight to blockchain validation.
## Failure modes & recovery
| Symptom | Likely cause | Recovery |
| ------------------------------------------------ | ------------------------------------- | --------------------------------------------------------------------------------------- |
| `payment-request` returns 404 | Unknown short ID | Ask the user to re-check the link / short ID |
| `start-payment` returns 422 / conflict | Request already paid or expired | Re-fetch the request; if `openAmount == 0`, tell the user the request is settled |
| `progress` stays `Pending` > 5 min on TRC-20 | Tx not yet broadcast or wrong network | Confirm with the user that the tx was sent to the exact `walletAddress` and the memo |
| `progress` returns `Error` from the pipeline | MaxCheckCount, blacklist, invalid quote | Contact <support@nicky.me> with the `paymentAttemptId` — do not retry the same attempt |
| `progress` returns `Expired` | 30-minute window closed | Start a new attempt |
## References
- [REST API reference](./references/api.md) — every endpoint, request body, and response field
- [MCP reference](./references/mcp.md) — MCP tool signatures and examples
- [OpenAPI spec (agents)](https://api-public.pay.nicky.me/openapi/agents.json)
- [OpenAPI spec (full public API)](https://api-public.pay.nicky.me/openapi/v1.json)
- [Interactive API docs](https://api-public.pay.nicky.me/scalar)
- [Agent integration guide](https://api-public.pay.nicky.me/agents.md)
- [Nicky llms.txt](https://pay.nicky.me/llms.txt) — LLM-facing platform overview
## Support
For payment issues, direct the user to <support@nicky.me> and include the
`paymentAttemptId` and (if available) the `transactionHash`. Do not invent status updates —
only what `GET /payment/progress` returns is authoritative.
don't have the plugin yet? install it then click "run inline in claude" again.
separated intent, inputs (with edge cases), procedure (with explicit in-out per step), decision points (8 explicit if-else branches), output contract (format and location), and outcome signal (success and failure criteria); added auth expiry fallback, rate limit handling, timeout retry logic, memo requirement, and 404 / 422 error recovery.
use this skill to discover nicky cryptocurrency payment requests and send funds on behalf of a user, end to end. nicky is a crypto payment platform where a receiver creates a short payment link (profile or specific request), and anyone (including an ai agent) can discover the request, receive a wallet address, and send funds. nicky handles on-chain monitoring, asset conversion, and confirmation. use this skill when the user asks to pay a nicky request, send crypto to a nicky link, check payment confirmation status, report a blockchain transaction hash, or look up accepted assets. do not use this if the user only wants to receive crypto on nicky (direct them to https://pay.nicky.me instead).
required context:
https://pay.nicky.me/payment-report/ABCDE?paymentId=VWXYZ), short payment id (e.g. #VWXYZ), or profile link (https://pay.nicky.me/s/ABCDE)optional external connections:
NICKY_API_KEY env var: optional api key for private mcp endpoint (enables account tools, balance queries, billing, credit transfers). if not set, skill runs on public endpoints only.https://api-public.pay.nicky.me/mcp-public/) for tooling. private mcp at https://api-public.pay.nicky.me/mcp/ available if api key set.edge cases to handle:
availableAssets list is empty, reject the request and ask user for a different one.resolve the short id from the user message or shared url.
https://pay.nicky.me/payment-report/ABCDE?paymentId=VWXYZ, extract VWXYZ as the short id.#VWXYZ or just VWXYZ, use that value as short id.https://pay.nicky.me/s/ABCDE (profile only, no payment request), ask the user for a specific request link or short id instead.shortId string ready for api call.discover the payment request via rest api or mcp.
shortId from step 1.GET /payment-request/{shortId} (rest) or GetPaymentRequest(shortId) (mcp).receiverUser, description, invoiceReference, totalAmount, openAmount, nativeAssetId, status, availableAssets list.openAmount == 0, request is already paid; inform user and offer to check another one.collect payer details from the user.
payerName (required, displayed to receiver).payerEmail (required, receiver uses this to identify who paid).select the payment asset.
availableAssets list from step 2, user preference if stated.availableAssets; else reject and ask again.nativeAssetId (no conversion); if user open to conversion, pick any accepted asset and nicky will convert.assetId string.availableAssets is empty, reject the entire request; direct user to contact receiver.start the payment via rest api or mcp.
shortId, assetId, payerName, payerEmail.POST /payment/start (rest) or StartPayment(paymentRequestShortId, assetId, payerName, payerEmail) (mcp).paymentAttemptId, walletAddress, amountToSend, assetId, memo (may be null), paymentRequestShortId, expiresAt (unix timestamp or iso string).instruct the user (or agent's own wallet) to send funds.
walletAddress, amountToSend, assetId, memo (if non-null), expiresAt.amountToSend of assetId to walletAddress".memo is non-null, include: "include memo memo if your wallet requires it".expiresAt (30 minutes); funds sent after this may not auto-match".(recommended) report the transaction hash as soon as broadcast.
transactionHash from user or agent's wallet.POST /payment/report-transaction (rest) or ReportTransaction(paymentAttemptId, transactionHash) (mcp).poll for confirmation every 15-30 seconds.
paymentAttemptId from step 5.GET /payment/progress/{paymentAttemptId} (rest) or GetPaymentProgress(paymentAttemptId) (mcp) in a loop.status field (see decision points below).status == "Confirmed" or isPaid == true.if short id cannot be resolved from user message:
if openAmount == 0 after fetching request:
if availableAssets is empty:
if user does not specify which asset to send:
nativeAssetId (no conversion). if user is open to conversion, pick any asset in availableAssets and explain nicky will convert.if start-payment returns 422 (conflict):
openAmount == 0, inform user the request is settled.openAmount > 0, something else conflicted (e.g. duplicate request); ask support@nicky.me for investigation.if 30-minute window (expiresAt) has passed before funds are sent:
start-payment again to issue a fresh address.start-payment is idempotent for same payer + request + asset, so prior attempt can be abandoned.if polling returns status == "Pending" after 5+ minutes on trc-20:
if polling returns status == "Received":
if polling returns status == "Confirmed":
if polling returns status == "Expired":
if polling returns status == "Error" or any non-standard status:
paymentAttemptId and any error details from response.paymentAttemptId."if api call returns 429 (rate limited):
if api call returns 401 and api key was supplied:
if network timeout occurs:
if memo is non-null in start-payment response:
on successful payment confirmation, the skill outputs:
amountToSend of assetId was sent to receiverUser and matched to the request."paymentAttemptId, walletAddress, transactionHash (if reported), status == "Confirmed", expiresAt, and receiver name.on failure (expired window, conflict, network error, or error status), the skill outputs:
paymentAttemptId and direct user to support@nicky.me.the user knows the skill worked when:
status == "Confirmed" or isPaid == true. the skill displays: "payment confirmed and credited to the receiver."Pending / Received to Confirmed.the skill failed if:
status == "Expired" without receiving funds (user did not send in time).status == "Error" with a non-recoverable error code.start-payment returns 422 and re-fetch shows request is already settled.