D9m1n1c

---
name: AIOT Network
description: Meta-skill that indexes all AIOT platform skills and routes agent requests to the correct sub-skill.
version: 1.0.0
metadata:
  openclaw:
    requires:
      env:
        - AIOT_API_BASE_URL
    primaryEnv: AIOT_API_BASE_URL
---

# AIOT Network

This is the routing index for the AIOT platform. Use it to determine which sub-skill handles a given user request, then delegate to that skill.

## Configuration

The default API base URL is `https://payment-api-dev.aiotnetwork.io`. All sub-skills use this as the base for API requests.

To override (e.g. for local development):

```bash
export AIOT_API_BASE_URL="http://localhost:8080"
```

If `AIOT_API_BASE_URL` is not set, use `https://payment-api-dev.aiotnetwork.io` as the base for all requests.

## Skill Index

| Skill | Install Slug | Use Cases |
|-------|-------------|-----------|
| Account & Authentication | `aiotnetwork-account-auth` | sign up, log in, manage sessions, reset their password, or link a Web3 wallet |
| KYC & Identity | `aiotnetwork-kyc-identity` | complete identity verification, upload KYC documents, or check verification status |
| Card Management | `aiotnetwork-card-management` | create virtual cards, view card details, or manage card lifecycle (lock, unlock, cancel) |
| Payments & Banking | `aiotnetwork-payments-banking` | top up a wallet, send money, make international remittances, or convert currencies |
| Crypto Wallet | `aiotnetwork-crypto-wallet` | deposit cryptocurrency into their wallet or withdraw to an external address |
| Blockchain & DID | `aiotnetwork-blockchain-did` | set up a decentralized identity, complete on-chain KYC, or manage membership tiers |

## Cross-Skill Dependencies

Some operations span multiple skills. Follow these dependency chains in order:

1. **Account → KYC → Card**: User must sign up (account-auth), complete KYC (kyc-identity), then create cards (card-management).
2. **Account → Payments**: User must be authenticated (account-auth) before any payment operation (payments-banking).
3. **Account → Crypto**: User must be authenticated (account-auth) before depositing or withdrawing crypto (crypto-wallet).
4. **Account → Blockchain DID**: User must be authenticated (account-auth) before creating a DID or staking (blockchain-did).
5. **KYC → Wallet KYC → Card**: MasterPay KYC (kyc-identity) must be approved, then wallet KYC submitted, before card creation (card-management).

## Agent Guidance

- When a user request matches a single skill, delegate directly to that skill.
- When a request spans multiple skills, follow the dependency chains above and execute skills in order.
- If the user has not completed a prerequisite (e.g., no account, KYC not approved), guide them through the prerequisite skill first.
- Each sub-skill contains its own detailed tool definitions, flows, rules, and guidance — always refer to the sub-skill for implementation details.

## Installation

To install all AIOT platform skills at once, run:

```bash
bash scripts/install.sh
```

Or install individual skills:

```bash
clawhub install aiotnetwork-account-auth
```
```bash
clawhub install aiotnetwork-kyc-identity
```
```bash
clawhub install aiotnetwork-card-management
```
```bash
clawhub install aiotnetwork-payments-banking
```
```bash
clawhub install aiotnetwork-crypto-wallet
```
```bash
clawhub install aiotnetwork-blockchain-did
```

FILE:scripts/install.sh
#!/usr/bin/env bash
set -euo pipefail

# Install all AIOT Network skills via ClawHub
# Usage: bash scripts/install.sh

SKILLS=(
  "aiotnetwork-account-auth"
  "aiotnetwork-kyc-identity"
  "aiotnetwork-card-management"
  "aiotnetwork-payments-banking"
  "aiotnetwork-crypto-wallet"
  "aiotnetwork-blockchain-did"
)

echo "Installing #SKILLS[@] AIOT Network skills..."
echo ""

FAILED=0
SUCCEEDED=0

for slug in "SKILLS[@]"; do
  echo "→ Installing slug..."
  if clawhub install "slug"; then
    ((SUCCEEDED++))
  else
    echo "  ✗ Failed to install slug"
    ((FAILED++))
  fi
done

echo ""
echo "Done. SUCCEEDED installed, FAILED failed."

if [ "FAILED" -gt 0 ]; then
  exit 1
fi

---
name: Blockchain & DID
description: Decentralized identity (DID) management, on-chain KYC status, and membership tiers with token staking.
version: 1.0.0
metadata:
  openclaw:
    requires:
      env:
        - AIOT_API_BASE_URL
    primaryEnv: AIOT_API_BASE_URL
---

# Blockchain & DID

Use this skill when the user needs to set up a decentralized identity, complete on-chain KYC, or manage membership tiers.

## Configuration

The default API base URL is `https://payment-api-dev.aiotnetwork.io`. All endpoints are relative to this URL.

To override (e.g. for local development):

```bash
export AIOT_API_BASE_URL="http://localhost:8080"
```

If `AIOT_API_BASE_URL` is not set, use `https://payment-api-dev.aiotnetwork.io` as the base for all requests.

## Available Tools

- `get_did_status` — Get the user's decentralized identity (DID) status | `GET /api/v1/blockchain/did` | Requires auth
- `create_did` — Create a new decentralized identity on-chain | `POST /api/v1/blockchain/did` | Requires auth
- `get_blockchain_kyc` — Get on-chain KYC verification status | `GET /api/v1/blockchain/kyc` | Requires auth
- `complete_blockchain_kyc` — Complete on-chain KYC at a given level (basic, standard, or enhanced) | `POST /api/v1/blockchain/kyc/complete` | Requires auth
- `get_membership` — Get membership status and tier | `GET /api/v1/blockchain/membership/status` | Requires auth
- `get_membership_tiers` — Get available membership tier configurations | `GET /api/v1/blockchain/membership/tiers` | Requires auth
- `stake_tokens` — Stake tokens to upgrade membership tier | `POST /api/v1/blockchain/membership/stake` | Requires auth

## Recommended Flows

### Setup Decentralized Identity

Create a DID and complete on-chain KYC

1. Check DID: GET /api/v1/blockchain/did — see if user already has a DID
2. Create DID: POST /api/v1/blockchain/did — if none exists
3. Check on-chain KYC: GET /api/v1/blockchain/kyc
4. Complete KYC: POST /api/v1/blockchain/kyc/complete with {level: basic|standard|enhanced}


### Upgrade Membership

Stake tokens to reach a higher membership tier

1. View tiers: GET /api/v1/blockchain/membership/tiers — see requirements
2. Check current: GET /api/v1/blockchain/membership/status
3. Stake: POST /api/v1/blockchain/membership/stake with {amount}


## Rules

- DID creation is a one-time operation — once active, it cannot be recreated
- On-chain KYC and off-chain (MasterPay) KYC are independent — completing one does not require the other
- Staking records the token amount for tier calculation — tier is determined by the staked amount
- Higher tiers unlock lower fees and additional features (Tier 1: 10%, Tier 2: 15%, Tier 3: 20%, Tier 4: 25% discount)

## Agent Guidance

Follow these instructions when executing this skill:

- Always follow the documented flow order. Do not skip steps.
- If a tool requires authentication, verify the session has a valid bearer token before calling it.
- If a tool requires a transaction PIN, ask the user for it fresh each time. Never cache or log PINs.
- Never expose, log, or persist secrets (passwords, tokens, full card numbers, CVVs).
- If the user requests an operation outside this skill's scope, decline and suggest the appropriate skill.
- If a step fails, check the error and follow the recovery guidance below before retrying.

- DID creation is a one-time operation. Once active, it cannot be recreated. Confirm with the user before calling `create_did`.
- On-chain KYC and off-chain (MasterPay) KYC are independent systems. Completing `complete_blockchain_kyc` does not require MasterPay KYC to be approved.
- `complete_blockchain_kyc` requires a `level` parameter: one of "basic", "standard", or "enhanced". Always ask the user which level they want.
- Staking sets the token amount that determines the membership tier. Tier is calculated from the staked amount: Tier 1 (0 tokens, 10%), Tier 2 (15,000 tokens, 15%), Tier 3 (20,000 tokens, 20%), Tier 4 (25,000 tokens, 25%).
- Higher membership tiers unlock lower transaction fees and additional platform features.

---
name: Crypto Wallet
description: Discover supported cryptocurrencies, generate deposit addresses, and withdraw crypto to external wallets.
version: 1.0.0
metadata:
  openclaw:
    requires:
      env:
        - AIOT_API_BASE_URL
    primaryEnv: AIOT_API_BASE_URL
---

# Crypto Wallet

Use this skill when the user needs to deposit cryptocurrency into their wallet or withdraw to an external address.

## Configuration

The default API base URL is `https://payment-api-dev.aiotnetwork.io`. All endpoints are relative to this URL.

To override (e.g. for local development):

```bash
export AIOT_API_BASE_URL="http://localhost:8080"
```

If `AIOT_API_BASE_URL` is not set, use `https://payment-api-dev.aiotnetwork.io` as the base for all requests.

## Available Tools

- `get_coins` — List all supported cryptocurrencies | `GET /api/v1/wallet/coins` | Requires auth
- `get_coin_networks` — List supported blockchain networks for a specific coin | `GET /api/v1/wallet/coins/:coin_id/networks` | Requires auth
- `get_deposit_address` — Generate or retrieve a deposit address for a coin on a specific network | `POST /api/v1/wallet/deposit/address` | Requires auth
- `get_withdraw_quote` — Get a quote for a crypto withdrawal (fees, limits) | `POST /api/v1/wallet/withdraw/quote` | Requires auth
- `initiate_withdraw` — Start a crypto withdrawal to an external address | `POST /api/v1/wallet/withdraw` | Requires auth
- `get_withdraw_status` — Check the status of a crypto withdrawal | `GET /api/v1/wallet/withdraw/:id` | Requires auth
- `confirm_withdraw` — Confirm a pending crypto withdrawal | `POST /api/v1/wallet/withdraw/:id/confirm` | Requires auth | Requires transaction PIN

## Recommended Flows

### Deposit Crypto

Generate a deposit address and fund your wallet with crypto

1. List coins: GET /api/v1/wallet/coins — find the coin you want to deposit
2. Get networks: GET /api/v1/wallet/coins/:coin_id/networks — choose the blockchain network
3. Get address: POST /api/v1/wallet/deposit/address with {coin_id, network_id} — returns deposit address
4. Send crypto to the returned address from your external wallet


### Withdraw Crypto

Send crypto from your wallet to an external address

1. Get quote: POST /api/v1/wallet/withdraw/quote with {coin_id, network_id, amount, address}
2. Initiate: POST /api/v1/wallet/withdraw with quote details
3. Confirm: POST /api/v1/wallet/withdraw/:id/confirm (requires transaction PIN)
4. Track: GET /api/v1/wallet/withdraw/:id — monitor until completed


## Rules

- Always verify the correct network before depositing — sending to the wrong network will lose funds
- Withdrawal follows a quote-then-confirm pattern — confirmation requires a transaction PIN
- Deposit addresses are deterministic — the same coin+network always returns the same address

## Agent Guidance

Follow these instructions when executing this skill:

- Always follow the documented flow order. Do not skip steps.
- If a tool requires authentication, verify the session has a valid bearer token before calling it.
- If a tool requires a transaction PIN, ask the user for it fresh each time. Never cache or log PINs.
- Never expose, log, or persist secrets (passwords, tokens, full card numbers, CVVs).
- If the user requests an operation outside this skill's scope, decline and suggest the appropriate skill.
- If a step fails, check the error and follow the recovery guidance below before retrying.

- Always verify the user selected the correct blockchain network before generating a deposit address. Sending to the wrong network will permanently lose funds.
- Withdrawal follows: get quote → initiate → confirm with transaction PIN. The confirmation step requires a 4-digit transaction PIN. Never skip the quote step.
- Deposit addresses are deterministic — the same coin + network always returns the same address.

---
name: Payments & Banking
description: Fund wallets, transfer money, send remittances, and convert currencies. Includes top-up via multiple payment methods and international money transfers.
version: 1.0.0
metadata:
  openclaw:
    requires:
      env:
        - AIOT_API_BASE_URL
    primaryEnv: AIOT_API_BASE_URL
---

# Payments & Banking

Use this skill when the user needs to top up a wallet, send money, make international remittances, or convert currencies.

## Configuration

The default API base URL is `https://payment-api-dev.aiotnetwork.io`. All endpoints are relative to this URL.

To override (e.g. for local development):

```bash
export AIOT_API_BASE_URL="http://localhost:8080"
```

If `AIOT_API_BASE_URL` is not set, use `https://payment-api-dev.aiotnetwork.io` as the base for all requests.

## Available Tools

- `get_balance` — Get current account balance | `GET /api/v1/bank/balance` | Requires auth
- `get_masterpay_balance` — Get MasterPay main wallet balance | `GET /api/v1/masterpay/balance` | Requires auth
- `list_card_wallets` — List all MasterPay card wallets and balances | `GET /api/v1/masterpay/wallets` | Requires auth
- `get_topup_methods` — Get available payment methods for top-up | `GET /api/v1/bank/topup/payment_methods` | Requires auth
- `get_topup_quote` — Get a quote for a top-up amount | `POST /api/v1/bank/topup/quote` | Requires auth
- `initiate_topup` — Start a top-up transaction | `POST /api/v1/bank/topup` | Requires auth
- `get_topup_status` — Check status of a top-up | `GET /api/v1/bank/topup/:id` | Requires auth
- `confirm_topup` — Confirm a pending top-up | `POST /api/v1/bank/topup/:id/confirm` | Requires auth
- `get_transfer_quote` — Get a quote for a transfer | `POST /api/v1/bank/transfer/quote` | Requires auth
- `initiate_transfer` — Start a money transfer | `POST /api/v1/bank/transfer` | Requires auth
- `get_transfer_status` — Check status of a transfer | `GET /api/v1/bank/transfer/:id` | Requires auth
- `confirm_transfer` — Confirm a pending transfer | `POST /api/v1/bank/transfer/:id/confirm` | Requires auth | Requires transaction PIN
- `get_remittance_countries` — Get supported remittance destination countries | `GET /api/v1/bank/transfer/remittance/countries` | Requires auth
- `get_exchange_rate` — Get current exchange rate for a currency pair | `GET /api/v1/bank/transfer/remittance/rate` | Requires auth
- `get_remittance_reference_data` — Get reference data for remittance forms (banks, branches, etc.) | `GET /api/v1/bank/transfer/remittance/reference-data` | Requires auth
- `get_remittance_quote` — Get a quote for an international remittance | `POST /api/v1/bank/transfer/remittance/quote` | Requires auth
- `initiate_remittance` — Start an international remittance | `POST /api/v1/bank/transfer/remittance` | Requires auth
- `get_remittance_status` — Check status of a remittance | `GET /api/v1/bank/transfer/remittance/:id` | Requires auth
- `get_remittance_history` — Get remittance transaction history | `GET /api/v1/bank/transfer/remittance/history` | Requires auth
- `confirm_remittance` — Confirm a pending remittance | `POST /api/v1/bank/transfer/remittance/:id/confirm` | Requires auth | Requires transaction PIN
- `cancel_remittance` — Cancel a pending remittance | `POST /api/v1/bank/transfer/remittance/:id/cancel` | Requires auth
- `list_recipients` — List saved remittance recipients | `GET /api/v1/bank/transfer/remittance/recipients` | Requires auth
- `create_recipient` — Save a new remittance recipient | `POST /api/v1/bank/transfer/remittance/recipients` | Requires auth
- `get_recipient` — Get details of a saved recipient | `GET /api/v1/bank/transfer/remittance/recipients/:recipient_id` | Requires auth
- `update_recipient` — Update a saved recipient's details | `PUT /api/v1/bank/transfer/remittance/recipients/:recipient_id` | Requires auth
- `delete_recipient` — Delete a saved recipient | `DELETE /api/v1/bank/transfer/remittance/recipients/:recipient_id` | Requires auth
- `get_conversion_pairs` — Get available currency conversion pairs | `GET /api/v1/bank/convert/pairs` | Requires auth
- `get_conversion_rate` — Get conversion rate between two currencies | `GET /api/v1/bank/convert/rate` | Requires auth
- `initiate_conversion` — Start a currency conversion | `POST /api/v1/bank/convert` | Requires auth
- `confirm_conversion` — Confirm a pending conversion | `POST /api/v1/bank/convert/:id/confirm` | Requires auth | Requires transaction PIN
- `list_transactions` — List transaction history with pagination | `GET /api/v1/transactions` | Requires auth
- `get_transaction` — Get details of a specific transaction | `GET /api/v1/transactions/:id` | Requires auth
- `download_receipt` — Download a transaction receipt as PDF | `GET /api/v1/transactions/:id/receipt/pdf` | Requires auth

## Recommended Flows

### Top Up Wallet

Add funds to your wallet via available payment methods

1. Get payment methods: GET /api/v1/bank/topup/payment_methods
2. Get quote: POST /api/v1/bank/topup/quote with {amount, currency, payment_method}
3. Initiate: POST /api/v1/bank/topup with quote details
4. Confirm: POST /api/v1/bank/topup/:id/confirm


### Send Remittance

Send money internationally to a recipient

1. Check countries: GET /api/v1/bank/transfer/remittance/countries
2. Get exchange rate: GET /api/v1/bank/transfer/remittance/rate?from=USD&to=PHP
3. Create or select recipient: POST/GET /api/v1/bank/transfer/remittance/recipients
4. Get quote: POST /api/v1/bank/transfer/remittance/quote
5. Initiate: POST /api/v1/bank/transfer/remittance
6. Confirm: POST /api/v1/bank/transfer/remittance/:id/confirm (requires transaction PIN)


## Rules

- All financial operations require authentication
- Top-ups and transfers follow a quote-then-confirm pattern — never skip the quote step
- Transfer, remittance, and conversion confirmations require a transaction PIN — top-up confirmations do not
- Remittances require a saved recipient — create one first if needed
- Exchange rates are indicative and may change between quote and confirmation
- Transaction history is paginated — use page and page_size query parameters

## Agent Guidance

Follow these instructions when executing this skill:

- Always follow the documented flow order. Do not skip steps.
- If a tool requires authentication, verify the session has a valid bearer token before calling it.
- If a tool requires a transaction PIN, ask the user for it fresh each time. Never cache or log PINs.
- Never expose, log, or persist secrets (passwords, tokens, full card numbers, CVVs).
- If the user requests an operation outside this skill's scope, decline and suggest the appropriate skill.
- If a step fails, check the error and follow the recovery guidance below before retrying.

- All financial operations follow a quote-then-confirm pattern. Always get a quote first — never skip directly to initiation.
- Transfer, remittance, and conversion confirmations require a transaction PIN. Top-up confirmations do not require a PIN.
- Remittances require a saved recipient. Create one with `create_recipient` if none exists.
- Exchange rates shown in quotes are indicative. The final rate is locked at confirmation.
- Transaction history is paginated. Use `page` and `page_size` query parameters.

---
name: Card Management
description: Create and manage virtual cards via MasterPay Global. Supports single-use cards for one-time purchases and multi-use cards for repeated use.
version: 1.0.0
metadata:
  openclaw:
    requires:
      env:
        - AIOT_API_BASE_URL
    primaryEnv: AIOT_API_BASE_URL
---

# Card Management

Use this skill when the user needs to create virtual cards, view card details, or manage card lifecycle (lock, unlock, cancel).

## Configuration

The default API base URL is `https://payment-api-dev.aiotnetwork.io`. All endpoints are relative to this URL.

To override (e.g. for local development):

```bash
export AIOT_API_BASE_URL="http://localhost:8080"
```

If `AIOT_API_BASE_URL` is not set, use `https://payment-api-dev.aiotnetwork.io` as the base for all requests.

## Available Tools

- `list_card_wallets` — List all MasterPay card wallets and balances (required before card creation) | `GET /api/v1/masterpay/wallets` | Requires auth
- `create_single_use_card` — Create a single-use virtual card for a one-time purchase | `POST /api/v1/masterpay/cards/single-use` | Requires auth
- `create_multi_use_card` — Create a multi-use virtual card for repeated purchases | `POST /api/v1/masterpay/cards/multi-use` | Requires auth
- `list_cards` — List all cards in a wallet (defaults to first wallet) | `GET /api/v1/masterpay/wallets/cards` | Requires auth
- `list_cards_by_wallet` — List cards for a specific wallet UUID | `GET /api/v1/masterpay/wallets/:wallet_uuid/cards` | Requires auth
- `get_card` — Get details of a specific card by UUID (includes card ATM PIN, no transaction PIN required) | `GET /api/v1/masterpay/cards/:id` | Requires auth
- `get_card_details` — Get full unmasked card number, CVV, and expiry (sensitive) | `POST /api/v1/masterpay/cards/:id/details` | Requires auth | Requires transaction PIN
- `get_card_types` — Get available card types and their properties | `GET /api/v1/masterpay/cards/types` | Requires auth
- `lock_card` — Lock (block) a card to prevent transactions | `POST /api/v1/masterpay/cards/:id/lock` | Requires auth | Requires transaction PIN
- `unlock_card` — Unlock (reactivate) a previously locked card | `POST /api/v1/masterpay/cards/:id/unlock` | Requires auth | Requires transaction PIN
- `cancel_card` — Permanently cancel (suspend) a card | `POST /api/v1/masterpay/cards/:id/cancel` | Requires auth | Requires transaction PIN
- `list_applied_cards` — List all card applications and their status | `GET /api/v1/cards` | Requires auth
- `get_applied_card` — Get details of a specific card application | `GET /api/v1/cards/:id` | Requires auth
- `apply_card` — Apply for a new payment card (physical or virtual) | `POST /api/v1/cards/apply` | Requires auth

## Recommended Flows

### Create a Virtual Card (MasterPay)

Create a single-use or multi-use virtual card via MasterPay

1. Check KYC status: GET /api/v1/masterpay/kyc/status — must be 'approved' (use get_kyc_status from kyc-identity skill)
2. List wallets: GET /api/v1/masterpay/wallets — verify at least one wallet exists (no wallets means KYC is not yet approved)
3. Submit wallet KYC: POST /api/v1/masterpay/wallets/kyc — required before card creation. Needs profile phone number and id_number set via PUT /profile/document (id_number is sent as orgCode to MasterPay)
4. Create card: POST /api/v1/masterpay/cards/single-use or /multi-use — returns masked PAN and card ATM PIN
5. Get full details: POST /api/v1/masterpay/cards/:id/details (requires transaction PIN) — returns full card number and CVV


### Apply for a Card

Apply for a new physical or virtual card via the card application flow

1. Get card types: GET /api/v1/masterpay/cards/types — see available types (silver, gold, titanium, hybrid_metal, digital_virtual, digital_virtual_2)
2. Apply: POST /api/v1/cards/apply with {card_type, delivery_method, full_name, phone_number, email, address?}
3. Track: GET /api/v1/cards/:id — check application status


## Rules

- KYC must be approved AND wallet KYC must be submitted (POST /masterpay/wallets/kyc) before creating any MasterPay card — card creation fails with NO_WALLETS if KYC is not complete, and MasterPay rejects cards if wallet KYC is missing
- MasterPay card responses include a masked PAN and the card ATM PIN — use /cards/:id/details with transaction PIN for the full card number and CVV
- The card ATM PIN (visible in get_card, list_cards, and card creation responses) is for ATM/POS use — it is different from the transaction PIN used for sensitive operations
- Lock/unlock/cancel operations require transaction PIN verification
- Cancelled cards cannot be reactivated — cancellation is permanent
- Card application (POST /cards/apply) requires card_type (silver/gold/titanium/hybrid_metal/digital_virtual/digital_virtual_2) and delivery_method (delivery/on_the_spot)
- Card application (/cards/apply) is for ordering new cards — use /masterpay/cards/single-use or /multi-use for instant virtual card creation

## Agent Guidance

Follow these instructions when executing this skill:

- Always follow the documented flow order. Do not skip steps.
- If a tool requires authentication, verify the session has a valid bearer token before calling it.
- If a tool requires a transaction PIN, ask the user for it fresh each time. Never cache or log PINs.
- Never expose, log, or persist secrets (passwords, tokens, full card numbers, CVVs).
- If the user requests an operation outside this skill's scope, decline and suggest the appropriate skill.
- If a step fails, check the error and follow the recovery guidance below before retrying.

- The full prerequisite chain is: KYC approved → wallet exists → wallet KYC submitted → card creation. Use `get_kyc_status` from the kyc-identity skill to verify KYC approval, then `list_card_wallets` to confirm a wallet exists. If no wallets exist, KYC is not yet approved. Then submit wallet KYC (POST /masterpay/wallets/kyc) before creating any card — MasterPay rejects card creation without wallet KYC.
- MasterPay card responses (creation, `get_card`, `list_cards`) include the card ATM PIN in the response — no transaction PIN is needed to see it.
- To get the full unmasked card number and CVV, call `get_card_details` with the user's transaction PIN. This is the only way to retrieve the full PAN and CVV.
- The card ATM PIN (for ATM/POS use) is different from the transaction PIN (the user's security PIN for sensitive operations like viewing full card details, locking, unlocking, or cancelling).
- Lock, unlock, and cancel operations all require the transaction PIN.
- Cancelled cards cannot be reactivated. Confirm with the user before cancelling.

---
name: KYC & Identity
description: Know-Your-Customer verification via MasterPay Global. Submit personal data, upload identity documents, and track approval status.
version: 1.0.0
metadata:
  openclaw:
    requires:
      env:
        - AIOT_API_BASE_URL
    primaryEnv: AIOT_API_BASE_URL
---

# KYC & Identity

Use this skill when the user needs to complete identity verification, upload KYC documents, or check verification status.

## Configuration

The default API base URL is `https://payment-api-dev.aiotnetwork.io`. All endpoints are relative to this URL.

To override (e.g. for local development):

```bash
export AIOT_API_BASE_URL="http://localhost:8080"
```

If `AIOT_API_BASE_URL` is not set, use `https://payment-api-dev.aiotnetwork.io` as the base for all requests.

## Available Tools

- `create_masterpay_user` — Create a MasterPay user account (prerequisite for all MasterPay operations) | `POST /api/v1/masterpay/users` | Requires auth
- `get_kyc_status` — Check current KYC verification status and document upload progress | `GET /api/v1/masterpay/kyc/status` | Requires auth
- `get_kyc_metadata` — Get valid document types, occupations, nationalities, and countries for KYC forms | `GET /api/v1/masterpay/kyc/metadata` | Requires auth
- `submit_kyc` — Submit KYC personal data for review (uses profile data) | `POST /api/v1/masterpay/kyc/submit` | Requires auth
- `upload_kyc_document` — Upload a KYC document (passport, ID, proof of address) via multipart or base64 JSON | `POST /api/v1/masterpay/kyc/documents` | Requires auth
- `submit_wallet_kyc` — Submit wallet-level KYC for a card wallet (requires profile phone number and identity document ID number) | `POST /api/v1/masterpay/wallets/kyc` | Requires auth
- `get_profile` — Get user profile data used for KYC submission | `GET /api/v1/profile` | Requires auth
- `update_profile` — Update user profile data (english_first_name, english_last_name, dob, gender, nationality, occupation, source_of_fund, phone_number, phone_country_code, country, address1, address2, address3, city, state, zip, billing_same_as_home) | `PUT /api/v1/profile` | Requires auth
- `get_document` — Get stored identity document info | `GET /api/v1/profile/document` | Requires auth
- `update_document` — Update identity document (fields: identity_type (passport|identity_card), id_number — id_number is required for wallet KYC) | `PUT /api/v1/profile/document` | Requires auth

## Recommended Flows

### Complete KYC Verification

Full flow from profile setup to KYC approval

0. Create MasterPay user: POST /api/v1/masterpay/users — required once before any MasterPay operation
1. Get metadata: GET /api/v1/masterpay/kyc/metadata — learn valid nationalities, occupations, document types
2. Update profile: PUT /api/v1/profile with {english_first_name, english_last_name, dob (YYYY-MM-DD), gender, phone_number, phone_country_code (with '+' prefix, e.g. '+65'), nationality, occupation (use value from metadata endpoint), source_of_fund, country (e.g. 'SG', 'ARGENTINA'), address1, city, state, zip, billing_same_as_home: true}
3. Upload documents: POST /api/v1/masterpay/kyc/documents — JSON body: {document_type, file_data (base64), file_name, mime_type (image/jpeg|image/png|application/pdf)}. Valid document types: PassportFront, PassportBack, NationalIdFront, NationalIdBack, DrivingLicenseFront, DrivingLicenseBack, Selfie, ProofOfAddress. Also supports multipart/form-data with 'file' field.
4. Submit KYC: POST /api/v1/masterpay/kyc/submit — uses profile data, resolves country codes to names, and sends to MasterPay
5. Poll status: GET /api/v1/masterpay/kyc/status — wait for 'approved' (can take minutes to days)


## Rules

- MasterPay user must be created (POST /masterpay/users) before any KYC, wallet, or card operation — this is a one-time setup step
- Profile must include personal info AND address fields (country, address1, city, state) before submitting KYC
- Use country names or ISO alpha-2 codes in the profile country field (e.g. 'SG', 'ARGENTINA') — the backend resolves them to full country names for MasterPay
- Phone country code in profile must include the '+' prefix (e.g. '+65') — MasterPay requires it
- Documents should be uploaded before submission — MasterPay requires passport/ID and proof of address, but our backend does not block submission without them
- KYC review can take minutes to several days — poll status periodically
- Once approved, KYC does not need to be repeated
- Document uploads support both JSON (document_type, file_data as base64, file_name, mime_type) and multipart/form-data (file field + document_type form field) — max 15MB per file

## Agent Guidance

Follow these instructions when executing this skill:

- Always follow the documented flow order. Do not skip steps.
- If a tool requires authentication, verify the session has a valid bearer token before calling it.
- If a tool requires a transaction PIN, ask the user for it fresh each time. Never cache or log PINs.
- Never expose, log, or persist secrets (passwords, tokens, full card numbers, CVVs).
- If the user requests an operation outside this skill's scope, decline and suggest the appropriate skill.
- If a step fails, check the error and follow the recovery guidance below before retrying.

- Before any KYC operation, ensure a MasterPay user exists by calling `create_masterpay_user`. This is a one-time setup. Other MasterPay handlers also auto-create the user, but calling it explicitly is good practice.
- Profile fields use these exact JSON keys: `english_first_name`, `english_last_name`, `dob` (format: YYYY-MM-DD), `gender`, `nationality`, `occupation`, `source_of_fund`, `phone_number`, `phone_country_code`.
- Occupation MUST be a value from the metadata endpoint (`get_kyc_metadata`). Valid values include: GovernmentOfficers, GovernmentWorkers, SoeAndStateOrganExecutives, SoeAndStateOrganEmployees, PrivateBusinessOwnersAndExecutives, PrivateBusinessEmployees, NonGovernmentOrganizationExecutives, NonGovernmentOrganizationEmployees, SoleTraders, Retirees, Students, Unemployed, Freelancer. Always call metadata first to get the current list.
- Complete profile (`update_profile`) with all required fields INCLUDING address fields (country, address1, city, state, zip, billing_same_as_home) before calling `submit_kyc`. The backend validates profile fields are present and returns 400 if any are missing.
- Document upload via JSON requires: `document_type` (e.g. PassportFront, NationalIdFront, Selfie, ProofOfAddress), `file_data` (base64-encoded), `file_name`, `mime_type` (image/jpeg, image/png, or application/pdf). Alternatively, use multipart/form-data with a `file` field and `document_type` form field.
- The `update_document` endpoint (PUT /profile/document) accepts: `identity_type` ("passport" or "identity_card") and `id_number` (passport number, NRIC, etc.). The `id_number` is sent as MasterPay's orgCode during wallet KYC. Always set `id_number` before calling `submit_wallet_kyc`.
- `submit_wallet_kyc` requires: (1) profile with phone_number + phone_country_code, (2) identity document with `id_number` set. It will fail with INCOMPLETE_PROFILE if `id_number` is missing.
- KYC review takes minutes to days. Poll `get_kyc_status` periodically — there are no push notifications.
- Use ISO alpha-2 country codes (e.g., "SG", "MY") for the profile country field. Include the "+" prefix for phone country codes (e.g., "+65").

---
name: Account & Authentication
description: Account signup, login via email/OTP/wallet/biometric, token refresh, password reset, and session management.
version: 1.0.0
metadata:
  openclaw:
    requires:
      env:
        - AIOT_API_BASE_URL
    primaryEnv: AIOT_API_BASE_URL
---

# Account & Authentication

Use this skill when the user needs to sign up, log in, manage sessions, reset their password, or link a Web3 wallet.

## Configuration

The default API base URL is `https://payment-api-dev.aiotnetwork.io`. All endpoints are relative to this URL.

To override (e.g. for local development):

```bash
export AIOT_API_BASE_URL="http://localhost:8080"
```

If `AIOT_API_BASE_URL` is not set, use `https://payment-api-dev.aiotnetwork.io` as the base for all requests.

## Available Tools

- `send_otp` — Send a one-time password to an email address | `POST /api/v1/auth/otp/send`
- `verify_otp` — Verify an OTP code and receive a verification token | `POST /api/v1/auth/otp/verify`
- `otp_rate_limit_status` — Check OTP rate limit status for the current session | `GET /api/v1/auth/otp/status`
- `signup` — Create a new account with email, password, and OTP verification token | `POST /api/v1/auth/signup`
- `login` — Login with email and password | `POST /api/v1/auth/login`
- `login_with_wallet` — Login by signing a nonce with a Web3 wallet | `POST /api/v1/auth/wallet`
- `get_wallet_nonce` — Get a nonce for wallet-based login | `GET /api/v1/auth/wallet/nonce`
- `biometric_login` — Login using biometric credentials | `POST /api/v1/auth/biometric`
- `refresh_token` — Refresh an expired access token using a refresh token | `POST /api/v1/auth/refresh`
- `reset_password` — Reset account password using OTP verification | `POST /api/v1/auth/reset-password`
- `unlock_account` — Unlock a locked account | `POST /api/v1/auth/unlock`
- `get_account` — Get current account information | `GET /api/v1/account` | Requires auth
- `update_password` — Change account password | `PUT /api/v1/account/password` | Requires auth
- `link_wallet` — Link a Web3 wallet to the account | `PUT /api/v1/account/wallet` | Requires auth
- `unlink_wallet` — Remove a linked Web3 wallet | `DELETE /api/v1/account/wallet` | Requires auth
- `logout` — Logout current session | `POST /api/v1/account/logout` | Requires auth
- `logout_all` — Logout from all sessions | `POST /api/v1/account/logout-all` | Requires auth

## Recommended Flows

### Sign Up

Create a new account via email and OTP

1. Send OTP: POST /api/v1/auth/otp/send with {email, type: "registration"}
2. Verify OTP: POST /api/v1/auth/otp/verify with {email, code, type: "registration"} — returns verification_token
3. Sign up: POST /api/v1/auth/signup with {email, password, verification_token}


### Login

Authenticate and receive access/refresh tokens

1. Login: POST /api/v1/auth/login with {email, password} — returns access_token, refresh_token
2. Use access_token as Bearer token in Authorization header for all authenticated requests
3. When access_token expires, refresh: POST /api/v1/auth/refresh with {refresh_token}


## Rules

- OTP is required for signup and password reset — always send then verify before proceeding
- Access tokens expire after 1 hour — use refresh_token to get a new one
- After 5 failed login attempts the account is locked — use /auth/unlock to recover
- Never store or log passwords — use them transiently only

## Agent Guidance

Follow these instructions when executing this skill:

- Always follow the documented flow order. Do not skip steps.
- If a tool requires authentication, verify the session has a valid bearer token before calling it.
- If a tool requires a transaction PIN, ask the user for it fresh each time. Never cache or log PINs.
- Never expose, log, or persist secrets (passwords, tokens, full card numbers, CVVs).
- If the user requests an operation outside this skill's scope, decline and suggest the appropriate skill.
- If a step fails, check the error and follow the recovery guidance below before retrying.

- To sign up a new user: first call `send_otp` with type "registration", then `verify_otp` with type "registration", then `signup`. Never skip OTP verification.
- Valid OTP types: "registration" (signup), "forget_password", "account_unlock", "pin_setup", "pin_reset". Always use the correct type for the operation.
- To reset a password: first call `send_otp` with type "forget_password", then `verify_otp`, then `reset_password` with the verification token.
- All authenticated endpoints require a bearer token obtained from `login` or `login_with_wallet`.
- When the access token expires (1 hour TTL), call `refresh_token` with the refresh token. Do not ask the user to log in again.
- Never log, store, or repeat the user's password back to them.
- If login fails 5 times consecutively, the account locks. To unlock: call `send_otp` with type "account_unlock", then `verify_otp`, then `unlock_account` with the verification token.