Crypto Payments

Turn a wallet address the user controls into a hosted crypto payment link or reusable tip jar via Shieldz, then read back how much has been paid. Non-custodial: funds settle straight to the user's wallet. Keyless: no account and no API key required.

Intent

This skill creates Shieldz crypto payment links (fixed-amount) or tip jars (pay-what-you-want) pointing to a wallet the user owns, and reads back payment totals. Use it only when the user explicitly asks to create a payment link, check a link's status, or set up a tip jar, has named the destination wallet, and has confirmed the amount (for fixed links). Every creation sends wallet address, chain, asset, amount, and optional email to shieldz.cash, a third-party service. Do not infer intent from vague phrasing, do not auto-create, and always confirm with the user before any external call.

Inputs

User-provided data:

• destination wallet address (required, must be user-confirmed)
• blockchain chain (required): BASE, ARBITRUM, OPTIMISM, POLYGON, or ETHEREUM
• asset (required): USDC or USDT
• amount in USD cents (required for payment links; omitted for tip jars)
• optional memo or title (string, max ~100 chars)
• optional email address (only if user explicitly provides and agrees to send it to Shieldz)
• manage_token (required only when reading status; user must provide this from a prior creation)

External connection:

• Shieldz REST API: https://shieldz.cash/api/v1/links, https://shieldz.cash/api/v1/tip-jars, https://shieldz.cash/a/<manage_token>.json
• Alternative MCP server: https://shieldz.cash/mcp (remote) or npx -y @shieldz/mcp@0.3.0 (local pinned version)
• No API key, OAuth, or credentials required
• No environment variables, local files, or keyring access needed

Data privacy note: On each request, Shieldz receives the wallet address, chain, asset, amount, memo, and optional email. The manage_token and manage_url are private capability secrets equivalent to passwords; treat them as such and never log, share, or post them.

Procedure

Step 1: Verify explicit user intent.

• Input: user's natural language request
• Action: confirm the user is asking to create a payment link, create a tip jar, or check the status of an existing link. do not activate on vague phrasing like "i need to get paid" or "how do payments work".
• Output: either confirmed intent (payment link, tip jar, or status check) or a clarifying question back to the user.

Step 2: Collect and confirm wallet and chain details.

• Input: user's wallet address and preferred chain
• Action: ask the user to state the exact wallet address and blockchain chain. repeat both back and confirm the user controls this wallet and consents to send the address to Shieldz.
• Output: confirmed wallet address (e.g., 0xabcd...) and chain (e.g., BASE).

Step 3: Collect and confirm amount (payment link only).

• Input: user's desired amount in USD or cents
• Action: if creating a fixed-amount payment link, ask the user for the amount in USD (or cents). confirm the amount is in the range $1 to $100k USD. repeat the amount back and get explicit "yes" before proceeding.
• Output: confirmed amount in USD cents (e.g., 4900 for $49.00).

Step 4: Collect asset preference.

• Input: user's preferred settlement asset
• Action: ask the user whether they want to receive USDC or USDT. confirm the selection.
• Output: confirmed asset (USDC or USDT).

Step 5: Collect optional memo and email.

• Input: user's optional memo/title and email
• Action: ask the user for an optional memo or title (for the payment link). separately, ask if they have an email address they wish to associate with this link (for dashboard access). warn that email is personal data sent to Shieldz; only include it if the user explicitly agrees.
• Output: optional memo (string) and optional email (string), or null if user declines.

Step 6: Final confirmation before external call.

• Input: all collected data (wallet, chain, asset, amount, memo, email choice)
• Action: restate all parameters back to the user. clearly note the wallet address, chain, asset, amount (if fixed link), memo, and whether email will be sent. ask for explicit "yes" or "approve" before making any HTTP call.
• Output: user confirmation (boolean true/false).

Step 7: Create payment link (fixed-amount only).

• Input: confirmed wallet, chain, asset, amount, memo, email (optional)
• Action: only if user approved in step 6. issue POST to https://shieldz.cash/api/v1/links with JSON body:

  {
    "settlement": {
      "chain": "<CHAIN>",
      "asset": "<ASSET>",
      "address": "<WALLET_ADDRESS>"
    },
    "amount_usd_cents": <AMOUNT>,
    "memo": "<MEMO>"
  }
  

  (omit "memo" if empty; omit entire "email" field if user did not provide one)
• Output: HTTP 200 or 201 response with pay_url, manage_url, and manage_token.

Step 8: Create tip jar (pay-what-you-want, reusable).

• Input: confirmed wallet, chain, asset, title, email (optional)
• Action: only if user approved in step 6 and opted for a tip jar. issue POST to https://shieldz.cash/api/v1/tip-jars with JSON body:

  {
    "settlement": {
      "chain": "<CHAIN>",
      "asset": "<ASSET>",
      "address": "<WALLET_ADDRESS>"
    },
    "title": "<TITLE>",
    "suggested_amounts_usd_cents": [300, 500, 1000]
  }
  

  (omit "email" field if user did not provide one)
• Output: HTTP 200 or 201 response with url and manage_token.

Step 9: Share public URL with user.

• Input: pay_url (from step 7) or url (from step 8)
• Action: provide the public payment link to the user. clearly separate it from the private manage_url or manage_token.
• Output: user-visible public URL.

Step 10: Secure the manage credentials.

• Input: manage_url and manage_token from step 7 or 8
• Action: inform the user that manage_url and manage_token are private credentials. advise them to store securely, never post publicly, never paste into logs or shared documents, and never share with third parties. do not log or echo these values yourself.
• Output: no further action; user acknowledgment.

Step 11: Read payment status (on user request).

• Input: user's manage_token for a previously created link or tip jar
• Action: only if the user provides a manage_token. issue GET to https://shieldz.cash/a/<manage_token>.json.
• Output: HTTP 200 response with account totals and invoice list.

Step 12: Report status to user.

• Input: response from step 11
• Action: parse and summarize the totals and recent invoices. present the data clearly to the user.
• Output: human-readable summary of payment status.

Decision Points

If the user's intent is vague or ambiguous (e.g., "i need to get paid", "how do i set up payments"):

• Do not create anything. ask a clarifying question. confirm the user wants a payment link, a tip jar, or status on an existing link before proceeding.

If the user has not provided a wallet address, or has not confirmed it is one they control:

• Do not proceed. ask the user to provide the wallet address and confirm ownership.

If the user is creating a fixed-amount payment link and has not confirmed the amount:

• Do not proceed. ask the user for the amount in USD, confirm it is in the $1-$100k range, and get explicit approval.

If the user has not explicitly provided an email address, or has declined to provide one:

• Omit the email field from the request body. email is optional and off by default.

If the user has provided an email address but has not explicitly agreed to send it to Shieldz:

• Ask the user to confirm consent before including the email in the request. do not assume consent.

If the user is reading the status of a link and provides no manage_token, or provides an invalid one:

• Do not make the GET request. ask the user for the correct manage_token from the original creation response.

If the Shieldz API returns a 4xx or 5xx error:

• Inform the user of the error. do not retry automatically. suggest they check the wallet address, chain, asset, and amount format. if the error persists, advise contacting Shieldz support.

If there is a network timeout or connection refused error:

• Inform the user that the connection to shieldz.cash failed. advise them to check their internet connection and try again. do not retry more than once without user approval.

If the API response is empty or missing expected fields (e.g., no pay_url or manage_token):

• Inform the user that the response was malformed. do not assume defaults. ask them to try again or contact Shieldz support.

If the user asks to use the MCP server instead of REST:

• Confirm whether they want the remote MCP server (https://shieldz.cash/mcp) or the local pinned version (npx -y @shieldz/mcp@0.3.0). call the appropriate create_payment_link, create_tip_jar, or get_account_status tool. apply the same confirmation and data-privacy rules as the REST flow.

If the user requests to create multiple payment links or tip jars in one session:

• Create them one at a time. confirm wallet, chain, asset, amount, and email for each before making any call. do not batch-create autonomously.

Output Contract

For payment link creation (success):

• HTTP 200 or 201 response body containing:
  • pay_url (string): public shareable URL, e.g., https://pay.shieldz.cash/p/xxxxx
  • manage_url (string): private dashboard URL, e.g., https://shieldz.cash/manage/xxxxx
  • manage_token (string): private capability token, used to read status
• Deliver pay_url to the user for sharing with payers.
• Store or return manage_token securely for future status checks; do not log or echo it.

For tip jar creation (success):

• HTTP 200 or 201 response body containing:
  • url (string): public shareable tip jar URL, e.g., https://tip.shieldz.cash/t/xxxxx
  • manage_token (string): private capability token for status checks
• Deliver url to the user for sharing.
• Store or return manage_token securely; do not log or echo it.

For payment status read (success):

• HTTP 200 response body containing:
  • totals (object): summary of USD received and any other metrics
  • invoices (array): list of individual payments with timestamps and amounts
• Parse and summarize for the user in human-readable format.

For all failures:

• HTTP 4xx or 5xx error response, or timeout, or malformed response.
• Report the error code and message to the user. do not hide technical details, but restate the likely cause (e.g., "invalid wallet address", "network timeout").

Storage and location:

• No local files created or modified.
• No data persisted on the user's machine.
• All interaction is transient request-response with shieldz.cash.

Outcome Signal

The skill has worked successfully when:

1. For payment link creation: the user receives a public pay_url they can immediately share with payers. they acknowledge the manage_token is private and stored securely. the link resolves in a browser and shows the expected amount and wallet.

2. For tip jar creation: the user receives a public url they can share. they understand the manage_token is private and secured. the tip jar resolves in a browser and shows the expected title and wallet.

3. For payment status check: the user receives a summary of the total amount received and a list of recent payments. the numbers match what they expect, and they can see timestamps for each invoice.

4. For all actions: no external data (wallet, amount, email) was sent to Shieldz without explicit user confirmation beforehand. the user confirmed the exact parameters before any HTTP call was made. the user was not surprised by the result.

5. Absence of outcome signal: the user is asked a clarifying question because intent, wallet, amount, or consent was unclear. no link or tip jar is created. the skill does not make an external call until the user approves.