# Nicky – AI Agent Instructions
# https://api-public.pay.nicky.me/agents.md

## What is Nicky?

Nicky is a crypto payment platform. Users share a short payment link (e.g. https://pay.nicky.me/ABCDE)
so that anyone – including AI agents – can pay them in cryptocurrency.

## Agent Capability: Pay a Payment Request

An AI agent can pay a Nicky payment request on behalf of a user by following the steps below.
Paying with any of the receiver's accepted assets is fully supported – conversion rates are applied
transparently by Nicky when a non-native asset is chosen.

---

## Step-by-Step: How to Pay a Payment Request

### 1. Identify the Payment Request Short ID

From a message like:
  "Pay payment request #ABCDEF on nicky.me"       → shortId = "ABCDEF"
  "Pay https://domain/payment-report/PIE01Y?paymentId=ABCDEF"               → shortId = "ABCDEF" (the part after paymentId=)

A shortId has a minimum length of 6 characters.

### 2. Discover Payment Details

GET https://api-public.pay.nicky.me/api/agents/payment-request?shortId=ABCDEF

Response includes:
  - receiverUser        – who receives the payment
  - totalAmount         – total amount requested
  - openAmount          – amount still unpaid
  - nativeAssetId       – the asset the request is denominated in (e.g. "USDT_TRC20")
  - availableAssets     – list of assets the receiver accepts
      - assetId         – asset identifier to use in start-payment
      - assetName       – human-readable name
      - isNativeAsset   – true for the primary asset of the request
      - amount          – exact open amount for the native asset; null for all other assets
                          (the exact converted amount is returned by start-payment)
  - payerInfoRequired   – { nameRequired: true, emailRequired: true }
  - status              – "PaymentPending" means the request is open and can be paid

### 3. Collect Payer Info (from the user)

Ask the user for:
  - Their full name  (e.g. "John Doe")
  - Their email      (e.g. "john@example.com")

These are required so the receiver can identify who paid.

### 4. Choose an Asset

Pick any assetId from the availableAssets list. If the user has no preference, use the native asset
(isNativeAsset == true) for the simplest flow. Any other accepted asset works too – Nicky handles
the conversion automatically.

### 5. Start the Payment

POST https://api-public.pay.nicky.me/api/agents/payment/start

Body (JSON):
  {
    "paymentRequestShortId": "ABCDEF",
    "assetId": "USDT_TRC20",
    "payerName": "John Doe",
    "payerEmail": "john@example.com"
  }

Response includes:
  - paymentAttemptId  – use this to track progress (e.g. "X7K2P1")
  - walletAddress     – send funds HERE
  - amountToSend      – send EXACTLY this amount (in the chosen asset, already converted)
  - assetId           – asset to send
  - expiresAt         – payment window closes at this time (30 minutes)

Conversion note: if you chose a non-native asset (e.g. ETH when the request is in USDT), Nicky
fetches a live conversion rate and returns the exact amount to send in ETH. The conversion is
verified by Nicky during payment matching.

### 6. Instruct the User to Send the Payment

Tell the user:
  "Please send exactly {amountToSend} {assetId} to {walletAddress} before {expiresAt}."
  "Memo/tag: {memo}" (only if memo is non-null)

If the agent controls a wallet, it can sign and broadcast the transaction directly.

### 7. (Optional) Report the Transaction Hash

Once you have the blockchain transaction hash, report it so Nicky can verify faster:

POST https://api-public.pay.nicky.me/api/agents/payment/report-transaction

Body:
  {
    "paymentAttemptId": "X7K2P1",
    "transactionHash": "abc123..."
  }

### 8. Poll for Confirmation

GET https://api-public.pay.nicky.me/api/agents/payment/progress?paymentAttemptId=X7K2P1

Poll every 15–30 seconds. The payment is complete when:
  - status == "Confirmed"   OR
  - isPaid == true

Status values:
  - Pending   – waiting for the transaction to appear on-chain
  - Received  – transaction detected, waiting for confirmation
  - Confirmed – payment confirmed and matched to the payment request
  - Expired   – payment window closed without a detected transaction

---

## MCP (Model Context Protocol) Server

Nicky exposes an MCP server for AI agents that support the Model Context Protocol:

**Public MCP** (no authentication required):
  https://api-public.pay.nicky.me/mcp-public/

Tools available via public MCP:
  - GetPaymentRequest   – discover payment details by short ID
  - StartPayment        – initiate a payment and get a wallet address
  - ReportTransaction   – report a blockchain transaction hash for faster verification
  - GetPaymentProgress  – poll payment confirmation status

**Server discovery:**
  - MCP server listing:  https://api-public.pay.nicky.me/.well-known/mcp.json
  - MCP server card:     https://api-public.pay.nicky.me/.well-known/mcp/server-card.json

---

## OpenAPI Specification

Machine-readable spec for all agent endpoints:
  https://api-public.pay.nicky.me/openapi/agents.json

Interactive documentation:
  https://api-public.pay.nicky.me/scalar  (select "Nicky Agents API" in the top-right)

---

## Notes

- All agent endpoints are anonymous – no API key required.
- The payment window is 30 minutes from the start-payment call. Call start-payment again to renew.
- Calling start-payment multiple times for the same payer + request + asset is idempotent and
  returns the same payment attempt (same wallet address and amount).
- Indicative amounts are NOT shown in the payment-request response for non-native assets.
  The exact converted amount is returned when you call start-payment.
- For questions or issues, contact support@nicky.me.