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. 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. 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. 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. Stop when status == "Confirmed" OR isPaid == true.

Status values#

GET /payment/progress returns one of:

StatusMeaningAgent actionPendingWaiting for the transaction to appear on-chain or in the queueKeep polling (or wait for the report-tx call)ReceivedTransaction detected, waiting for confirmationsKeep pollingConfirmedConfirmed, matched to the request, and creditedStop polling — report success to the userExpired30-minute window closed before any matching depositTell 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.

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 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.

StageWhat happensPolling intervalDeposit discoveryExchange connector polled for new depositsevery 30 sBlockchain validationOn-chain tx verified; 10+ confirmations requiredevery 60 sTransaction matchingDeposit matched to the payer's 30-minute address lease (±2% amount tolerance)every 35 sPayment report creationReport linked to the payment requestevery 45 sFinalizationFraud/blacklist checks, quote validation, confirmation email sentevery 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#

SymptomLikely causeRecoverypayment-request returns 404Unknown short IDAsk the user to re-check the link / short IDstart-payment returns 422 / conflictRequest already paid or expiredRe-fetch the request; if openAmount == 0, tell the user the request is settledprogress stays Pending > 5 min on TRC-20Tx not yet broadcast or wrong networkConfirm with the user that the tx was sent to the exact walletAddress and the memoprogress returns Error from the pipelineMaxCheckCount, blacklist, invalid quoteContact support@nicky.me with the paymentAttemptId — do not retry the same attemptprogress returns Expired30-minute window closedStart a new attempt

References#

• REST API reference — every endpoint, request body, and response field
• MCP reference — MCP tool signatures and examples
• OpenAPI spec (agents)
• OpenAPI spec (full public API)
• Interactive API docs
• Agent integration guide
• Nicky 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.