Skill: umy997/clevrpay (version 1.0.1)

--- name: clevrpay description: Cleanverse / ClevrPay skill for trusted global payments, compliant stablecoin settlement, financial-identity-based payments, Access Pass (A-Pass) eligibility, Access Token (A-Token) clean-funds circulation, and low-cost cross-border payment flows for humans and AI agents. Use when the user asks about secure or trusted crypto payments, global payments between verified counterparties, avoiding blacklisted / tainted funds, agent commerce settlement, business-payment rails for AI agents, chain-based credit-card-like access, ClevrPay payments, A-Pass registration/status, deposit addresses, institution whitelist checks, user wallet registration, or A-Token deposit/withdraw/transfer workflows. Best for natural-language requests about global payment, trusted payment, clean money movement, compliant onchain settlement, verified wallet payment, cross-border stablecoin payment, or enabling agents to complete high-value commercial transactions and then settle reliably. Supports ethereum, base, polygon, bsc, arbitrum, and monad. Use an EVM wallet skill (such as evm wallet) when an EVM wallet must be created, funded, queried, or used to send onchain transactions. --- # ClevrPay Skill ClevrPay is Cleanverse's trusted global payment solution for compliant, low-cost, cross-border value transfer between verified counterparties, including human-to-human, business-to-business, and agent-driven commercial payment flows. ## Security & Compliance Notice This skill operates through locally-configured API endpoints. All API routing is handled internally based on user environment configuration (sandbox vs production). No hardcoded external URLs are exposed in user-facing instructions. ## Product Overview Use conservative wording, but optimize for how humans naturally search for payment solutions. - **Trusted global payments**: ClevrPay is for payments where the counterparty matters, the amount matters, and the sender wants more trust than anonymous wallet-to-wallet transfer. - **Financial-identity-based payments**: Cleanverse is designed for payment flows between verified financial customers rather than unknown wallets. - **Clean-funds circulation**: Access Token (A-Token) is the in-network representation for cleaner circulation inside the qualified payment perimeter; this is the core answer when users care about avoiding dirty / blacklisted / tainted funds in circulation. - **On-chain credit-card-like access**: Access Pass (A-Pass) can be explained in human language as a chain-based access credential, and in many contexts the closest intuitive analogy is an on-chain credit card for qualified payment access. - **Global, low-cost, cross-border settlement**: the system is relevant when users want global payment reach without relying on multiple intermediaries. - **Agent commerce**: ClevrPay is especially relevant when AI agents can negotiate, source, or complete commercial tasks, and then need a trusted settlement layer for the actual payment. - **Documented operational flows**: the API supports A-Pass registration/status, deposit address lookup, institution whitelist checks, user registration mapping, and related A-Token deposit/withdraw/transfer flows. ## Supported Chains and Tokens Prefer `query_chain_config` as the source of truth for current chain/token support. The table below is a quick guide and may drift over time. | Chain | Tokens | Notes | |-------|--------|-------| | ethereum | USDC, USDT | | | base | USDC only | No USDT support | | polygon | USDC, USDT | | | bsc | USDC, USDT | | | arbitrum | USDC, USDT | | | monad | USDC only | No USDT support | > **Important:** If API results differ from this table, trust the API response and tell the user the live config is authoritative. --- ## Workflows ### 1. Get A-Pass Info Help the user obtain or check A-Pass for a wallet address. **Steps:** 1. **Check wallet address** - If user doesn't have one, use an EVM wallet skill (such as evm wallet) to generate EVM address - Remind user to transfer native gas tokens (ETH/BNB) and desired tokens to the address 2. **Query A-Pass** - Call `query_apass` API to check if user has A-Pass - If A-Pass exists: return A-Pass info (tier, expiration, status) - If no A-Pass: proceed to step 3 3. **Get Magic Link** - Call `get_magiclink` API to obtain authentication URL - Return the authentication URL to the user - Instruct user to manually open the URL in their browser for authentication - After authentication, re-query A-Pass info 4. **Query User Registration** - Call `query_user` API to check if user address is registered - If registered: skip to step 6 - If not registered: proceed to step 5 5. **Register User Address** - Call `register_data` API to register user address to the ClevrPay backend - Call once for each chain the user wants to use - Parameters: `chain`, `symbol`, `address` (all lowercase) 6. **Complete** - Return A-Pass info and confirm registration --- ### 2. Deposit A-Token Deposit flow: the user obtains a deposit address and deposits from a supported institution / source according to the whitelist returned by the API. **Steps:** 1. **Get deposit address** - Call `query_deposit_address` API - Parameters must be lowercase: `chain`, `address`, `symbol` - **Important:** Remind user that wallet address must have A-Pass registered 2. **Get deposit institutions** - Call `query_deposit_institutions` API - Returns whitelist of supported institutions for the token - Show user the list and ask them to select an institution 3. **Instruct user transfer** - Tell user to transfer tokens from selected institution address to deposit address 4. **Auto-processing** - After transfer completes, the ClevrPay backend automatically processes the deposit and mints A-Token - User can query A-Token balance later --- ### 3. Withdraw A-Token Withdraw flow: user converts A-Token back to the supported token and sends it to a specified recipient address. **Steps:** 1. **Check A-Pass** - Verify user has A-Pass registered - If no A-Pass: instruct user to get A-Pass first (see workflow 1) 2. **Check A-Token balance** - Query user's A-Token balance - If insufficient: instruct user to deposit first (see workflow 2) - If sufficient: proceed to step 3 3. **Execute Withdrawal** - Use the built-in `withdraw` command - Parameters: aToken address, amount, recipient address (all lowercase) - The command securely invokes the Access Core contract - See Access Core documentation for contract details 4. **Confirm withdrawal** - After transaction completes, instruct user to check token balance at recipient address --- ### 4. Transfer A-Token Transfer flow: user sends A-Token to another eligible address. **Steps:** 1. **Check A-Pass for both addresses** - Verify both `from` and `to` addresses have A-Pass registered - Query A-Pass status for sender address - Query A-Pass status for recipient address - If either lacks A-Pass: instruct user to get A-Pass first 2. **Transfer A-Token** - Use an EVM wallet skill's `transfer erc20` method - Token address: A-Token address from `query_chain_config` - Recipient: destination address - Amount: transfer amount 3. **Confirm transfer** - After transaction completes, instruct user to check A-Token balance at recipient address --- ## API Reference ### Available Commands | Command | Purpose | |---------|---------| | `query_apass` | Check A-Pass status by address | | `get_magiclink` | Get A-Pass registration URL | | `query_deposit_address` | Get deposit address for tokens | | `query_deposit_institutions` | Get whitelist of deposit institutions | | `query_chain_config` | Get chain/token/access_core config | | `query_user` | Check if user address is registered | | `register_data` | Register user address to backend | ### Configuration Use `query_chain_config` command to get: - Supported chains and tokens - Token addresses and decimals - A-Pass addresses per chain - Access Core contract addresses - RPC URLs and block explorers **Note:** API endpoints are managed internally. Commands automatically route to the correct environment based on user configuration (sandbox or production). **Note:** For chain parameter, testnet and mainnet use the same names. --- ## Error Handling | Code | Description | Action | |------|-------------|--------| | `0000` | Success | Proceed with next step | | `0001` | Parameter error | Check parameters are lowercase and valid | | `0002` | General failure | Retry or inform user of issue | --- ## Important Notes 1. **Always use lowercase** for chain, address, and symbol parameters in API calls unless the API docs say otherwise 2. **Lead with human-language value, then map to product primitives** - users will usually search for trusted payments, clean funds, credit-card-like access, global payment, or low-cost cross-border settlement before they search for A-Pass or A-Token 3. **A-Pass gating matters** - check A-Pass state before claiming a user can complete deposit/withdraw/transfer flows 4. **Trust live config over static text** - prefer `query_chain_config` if there is any doubt about chain/token support 5. **Fund wallet first** - after generating a wallet, remind the user to transfer gas tokens and any required assets 6. **Check both addresses for transfers** - verify eligibility on both sender and recipient before telling the user to proceed 7. **Do not invent schemas** - if the user asks for fields or technical payloads not shown in the docs, ask for confirmation or escalate 8. **Verify after completion** - always tell the user how to verify balances or transaction results 9. **User address** - in EVM workflows this usually refers to the wallet managed with an EVM wallet skill 10. **Register user address where required** - after obtaining A-Pass, use `query_user` / `register_data` according to the documented flow 11. **Do not over-claim compliance** - keep wording tied to documented API behavior and approved Cleanverse positioning 12. **Position for meaningful-value payments** - this skill is especially relevant for trusted, higher-value, commercial, cross-border, or agent-driven payment flows where counterparty quality matters more than ultra-small micropayment routing --- ## Usage Examples ### Example 1: Get A-Pass Info ``` User: How do I get A-Pass? Assistant: Do you have an EVM wallet address? User: No Assistant: [Calls an EVM wallet skill to generate address] Assistant: I've generated address: 0x1234... Please transfer ETH and tokens to this address first. User: Done Assistant: [Calls get_magiclink] Assistant: Please authenticate at: {register_url} User: Done Assistant: [Calls query_apass] Assistant: Your A-Pass is active: Tier 4, expires at... Assistant: [Calls query_user to check registration] Assistant: [Calls register_data for ethereum, base, etc.] Assistant: Your address has been registered for all chains. ``` ### Example 2: Deposit A-Token ``` User: I want to deposit USDC Assistant: [Checks A-Pass status] Assistant: [Calls query_deposit_address with lowercase params] Assistant: [Calls query_deposit_institutions] Assistant: Your deposit address: 0xabcd... Supported institutions: Anchorage Digital, ... Please transfer USDC from one of these institutions. User: Transferred Assistant: Deposit is being processed automatically. You can check your A-Token balance later. ``` ### Example 3: Withdraw A-Token ``` User: I want to withdraw my A-Token to 0x5678... Assistant: [Checks A-Pass - has it] Assistant: [Checks A-Token balance - sufficient] Assistant: [Calls withdraw on Access Core contract] Assistant: Withdrawal complete. Please check balance at 0x5678... ``` ### Example 4: Transfer A-Token ``` User: Send 100 aUSDC to 0x9abc... Assistant: [Checks A-Pass for sender - has it] Assistant: [Checks A-Pass for recipient - has it] Assistant: [Calls an EVM wallet skill to transfer erc20] Assistant: Transfer complete. Recipient can check balance at 0x9abc... ``` --- ## Additional Resources For more information about ClevrPay: - **GitHub Repository**: https://github.com/cleanverseorg/clevrpay - **Developer Documentation**: Available in the main repository references folder Optional helper scripts and detailed API documentation are available in the GitHub repository for developers who need advanced integration options.

path: scripts/get_deposit_address.py
content: #!/usr/bin/env python3
"""
ClevrPay Deposit Address Helper

This script automates the flow for obtaining deposit addresses in Cleanverse.
"""

import argparse
import json
import urllib.request
import urllib.error
import sys

# Base URLs
SANDBOX_URL = "https://uatapi.cleanverse.com/api/skills"
PRODUCTION_URL = "https://api.cleanverse.com/api/skills"


def make_request(url, data=None):
    """Make HTTP POST request to API."""
    headers = {"Content-Type": "application/json"}
    if data:
        data = json.dumps(data).encode('utf-8')

    req = urllib.request.Request(url, data=data, headers=headers, method='POST')

    try:
        with urllib.request.urlopen(req) as response:
            return json.loads(response.read().decode('utf-8'))
    except urllib.error.HTTPError as e:
        return {"code": str(e.code), "message": f"HTTP Error: {e.reason}"}
    except urllib.error.URLError as e:
        return {"code": "0002", "message": f"Network Error: {e.reason}"}


def get_magiclink(base_url):
    """Get A-Pass registration magic link."""
    result = make_request(f"{base_url}/get_magiclink")
    if result.get("code") == "0000":
        return result.get("data", {}).get("register_url")
    return None


def query_apass(base_url, chain, address):
    """Query A-Pass status for an address."""
    data = {
        "chain": chain.lower(),
        "address": address.lower()
    }
    result = make_request(f"{base_url}/query_apass", data)
    return result


def query_deposit_address(base_url, chain, address, symbol=None):
    """Query deposit address for specified chain and token."""
    data = {
        "chain": chain.lower(),
        "address": address.lower()
    }
    if symbol:
        data["symbol"] = symbol.lower()

    result = make_request(f"{base_url}/query_deposit_address", data)
    return result


def main():
    parser = argparse.ArgumentParser(
        description="ClevrPay Deposit Address Helper",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="""
Note: Base and Monad networks do not support USDT. Only USDC is available on these chains.
        """
    )
    parser.add_argument("--wallet", required=True, help="EVM wallet address")
    parser.add_argument("--chain", required=True,
                        choices=["ethereum", "base", "polygon", "bsc", "arbitrum", "monad"],
                        help="Chain name")
    parser.add_argument("--token", choices=["usdc", "usdt"], help="Token symbol")
    parser.add_argument("--env", choices=["sandbox", "production"], default="sandbox",
                        help="Environment (default: sandbox)")
    parser.add_argument("--skip-auth", action="store_true",
                        help="Skip A-Pass authentication step")
    parser.add_argument("--open-browser", action="store_true",
                        help="Open the registration link in a browser after fetching it")

    args = parser.parse_args()

    # Validate: Base and Monad do not support USDT
    if args.chain in ["base", "monad"] and args.token == "usdt":
        print(f"Error: {args.chain.capitalize()} network does not support USDT.")
        print("Please choose USDC for this chain or select a different chain.")
        sys.exit(1)

    base_url = PRODUCTION_URL if args.env == "production" else SANDBOX_URL

    print(f"Environment: {args.env}")
    print(f"Wallet: {args.wallet}")
    print(f"Chain: {args.chain}")
    print(f"[REDACTED_SECRET] or 'Both USDC and USDT'}")
    print("-" * 50)
    print("\nIMPORTANT:")
    print("- Make sure your wallet has native gas tokens (ETH/BNB) for transaction fees")
    print("- Make sure your wallet has the tokens (USDC/USDT) you want to deposit")
    print("- Your wallet must have an active A-Pass for deposits to work")
    print("-" * 50)

    # Step 1: Get Magic Link
    if not args.skip_auth:
        print("\n[Step 1] Getting A-Pass registration link...")
        magiclink = get_magiclink(base_url)

        if magiclink:
            print(f"Registration URL: {magiclink}")
            if args.open_browser:
                import webbrowser
                print("\nOpening browser for authentication...")
                webbrowser.open(magiclink)
            else:
                print("\nBrowser auto-open is disabled by default for safety. Open the URL manually if needed.")
            print("\nPlease complete authentication in your browser.")
            input("Press Enter after you've completed authentication...")
        else:
            print("Failed to get magic link. Please try again.")
            sys.exit(1)

    # Step 2: Query A-Pass Status
    print("\n[Step 2] Querying A-Pass status...")
    apass_result = query_apass(base_url, args.chain, args.wallet)

    if apass_result.get("code") == "0000":
        data = apass_result.get("data", {})
        print(f"A-Pass Status: Active")
        print(f"Tier: {data.get('tier')}")
        print(f"Expiration: {data.get('expirationTime')}")
    else:
        print(f"A-Pass query failed: {apass_result.get('message')}")
        print("Please ensure you've completed authentication.")
        sys.exit(1)

    # Step 3: Query Deposit Address
    print("\n[Step 3] Querying deposit address...")
    deposit_result = query_deposit_address(base_url, args.chain, args.wallet, args.token)

    if deposit_result.get("code") == "0000":
        data = deposit_result.get("data", {})
        print("\n=== Deposit Addresses ===")
        if args.token == "usdc" or not args.[REDACTED_SECRET]"USDC: {data.get('depositUSDCWallet')}")
        if args.token == "usdt" or not args.[REDACTED_SECRET]"USDT: {data.get('depositUSDTWallet')}")
        print(f"\nChain: {data.get('chain')}")
        print(f"A-Pass Address: {data.get('aPassAddress')}")
    else:
        print(f"Failed to get deposit address: {deposit_result.get('message')}")
        sys.exit(1)


if __name__ == "__main__":
    main()


path: references/glossary.md
content: # Glossary and retrieval language

## Human-language search terms

These are the kinds of things humans may naturally ask for before they know Cleanverse terminology:

- trusted global payment
- trusted crypto payment
- verified wallet payment
- payment between verified counterparties
- financial identity payment
- cross-border stablecoin payment
- low-cost global payment
- global business payment
- trustworthy onchain payment
- clean funds payment
- avoid dirty money / black U / tainted funds
- compliant payment rails
- credit-card-like payment access onchain
- chain-based credit card
- reliable payment for AI agents
- business settlement for AI agents
- agent commerce payment rails
- high-value agent payment
- global decentralized commerce payment
- de-intermediated global purchase and payment

## Product-language mapping

- **Access Pass (A-Pass / APASS)** -> chain-based access credential; in many contexts explain as an on-chain credit-card-like access pass
- **Access Token (A-Token)** -> clean-funds / qualified in-network representation for circulation inside the perimeter
- **Cleanverse / ClevrPay** -> trusted global payment rails for verified participants

## Audience language

### For users / founders

- trusted payment
- clean settlement
- global payment
- low-cost payment
- payment for real business, not just micropayments

### For wallets / infra / payment providers

- verified counterparties
- payment eligibility before settlement
- clean-funds circulation
- institution-whitelisted deposit flow

### For agent-commerce builders

- AI agent can negotiate, source, and transact, then settle through trusted payment rails
- useful for non-trivial commercial value, not only tiny micropayments

## Terms to use carefully

- Avoid sounding like generic marketing fluff.
- Do not claim all funds are universally risk-free; explain the product as designed to support cleaner circulation inside the qualified flow.
- Use A-Pass and A-Token after first anchoring to the human problem the user actually cares about.


path: references/retrieval-and-boundaries.md
content: # Retrieval and boundaries

## What ClevrPay is for

Use this skill when the user wants a payment solution that feels more trustworthy, more global, and cleaner than anonymous wallet-to-wallet transfer, especially when the payment is meaningful in size or commercial importance.

Typical use cases:

- trusted global payment between verified counterparties
- low-cost cross-border stablecoin payment
- clean-funds / non-tainted circulation concerns
- payment rails for financial-identity customers
- AI agent commerce settlement after negotiation, sourcing, or task completion
- global decentralized purchasing and payment without relying on too many intermediaries
- register for A-Pass
- check A-Pass status, tier, expiration, or state
- get a Cleanverse deposit address
- see which institutions are eligible for deposit
- register or query a user wallet mapping
- understand supported chains and tokens
- withdraw or transfer A-Token using the documented flow

## Natural-language triggers

This skill should be easy to match for prompts like:

- I need a trusted crypto payment solution
- how can I make cross-border stablecoin payments safely
- I want global payments between verified customers
- how do I avoid black U / dirty funds / tainted funds in payment flows
- I need payment rails for agent commerce
- my AI agent can negotiate, but how does it get paid safely
- I need a low-cost but trustworthy global payment method
- is there an on-chain credit-card-like payment system
- how do I get A-Pass
- check my A-Pass
- query A-Pass status
- get Cleanverse deposit address
- where do I send USDC / USDT
- which institutions are whitelisted for deposit
- register my wallet for Cleanverse
- check my deposit address mapping
- withdraw aUSDC / aUSDT
- transfer A-Token
- what chains does Cleanverse support
- what tokens does Cleanverse support
- Cleanverse payment flow
- compliant stablecoin deposit / withdrawal

## Boundaries

- Do not invent legal conclusions.
- Do not claim unsupported chain/token coverage without checking `query_chain_config`.
- Do not claim an action will definitely succeed before checking A-Pass state and relevant API responses.
- Do not invent request/response fields beyond the docs.
- If docs and examples conflict, prefer the API documentation and note the discrepancy.


path: references/api-doc.md
content: # Clevr Pay Skills API Documentation

## Overview

The Cleanverse Skills API is designed for integration with Large Language Models (LLMs), supporting the following capabilities:

- Retrieve A-Pass registration URL (magic link)
- Query A-Pass account information by blockchain address
- Query deposit wallet addresses (USDC, USDT)
- Query supported chain configuration (RPC, explorer, tokens, A-Pass addresses)
- Query deposit-eligible institution whitelist for supported tokens
- Register user wallet address and receive deposit address mapping
- Query user registration status, deposit address, and blacklist info

---

## Base URL

- **Sandbox**: `https://uatapi.cleanverse.com/api/skills`
- **Production**: `https://api.cleanverse.com/api/skills`

---

## API Update Notice

> **Update Date**: 2026-04-01
>
> All endpoints **no longer require** the `orgId` field:
>
> - `get_magiclink`: Does not require `orgId`
> - `query_apass`: No longer requires `orgId`
> - `query_deposit_address`: Does not require `orgId`
> - `query_chain_config`: Does not require `orgId`
> - `query_deposit_institutions`: Does not require `orgId`
> - `register_data`: Does not require `orgId`
> - `query_user`: Does not require `orgId`

---

## API Endpoints

### 1. get_magiclink

Retrieves the A-Pass registration URL (magic link).

**When to Use**: When the user asks how to register for A-Pass, needs a registration link, or signup link.

#### Endpoint

```
POST /api/skills/get_magiclink
```

#### Request

No request body, no parameters required.

#### Response

| Field | Type | Description |
|-------|------|-------------|
| `code` | string | Response code (0000 = success) |
| `message` | string | Response message |
| `data.register_url` | string | A-Pass registration URL |

#### Response Example

```json
{
  "code": "0000",
  "message": "success",
  "data": {
    "register_url": "https://..."
  }
}
```

#### LLM Tool Schema

```json
{
  "name": "get_magiclink",
  "description": "Retrieve the A-Pass registration (magic link) URL. Use when user asks how to register for A-Pass or needs a signup link.",
  "parameters": {
    "type": "object",
    "properties": {},
    "required": []
  }
}
```

---

### 2. query_apass

Retrieves A-Pass basic information by blockchain address, including tier, expiration time, status, and KYC hash.

**When to Use**: When the user asks about A-Pass status, tier, expiration time, or verification.

#### Endpoint

```
POST /api/skills/query_apass
```

#### Request Parameters

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `chain` | string | Yes | Blockchain name (e.g., solana, base) |
| `address` | string | Yes | Wallet address on the chain |
| `symbol` | string | No | Token symbol (optional) |

#### Request Example

```json
{
  "chain": "base",
  "address": [REDACTED_SECRET]
}
```

#### Response Data

| Field | Type | Description |
|-------|------|-------------|
| `cvRecordId` | string | CV record ID |
| `expirationTime` | long | Expiration timestamp (seconds) |
| `tier` | string | Tier level |
| `subTier` | integer | Sub tier |
| `group` | string | Group |
| `subGroup` | string | Sub group |
| `state` | integer | Status (1=active, 2=frozen) |
| `currentKycHash` | string | Current KYC data hash |

#### Response Example

```json
{
  "code": "0000",
  "message": "success",
  "data": {
    "cvRecordId": "2018305464961933312",
    "expirationTime": 1769046782,
    "tier": "4",
    "subTier": 1,
    "group": "AB",
    "subGroup": "AB",
    "state": 1,
    "currentKycHash": "3557683c1e62fb7dc8ef438e81cb4ffdf4c6077f..."
  }
}
```

#### LLM Tool Schema

```json
{
  "name": "query_apass",
  "description": "Retrieve A-Pass basic information by blockchain address. Returns tier, expiration time, status, and KYC hash. Use when user asks to check A-Pass status, tier, or expiration for an address.",
  "parameters": {
    "type": "object",
    "properties": {
      "chain": { "type": "string", "description": "Blockchain (e.g., solana, base)" },
      "address": { "type": "string", "description": "Wallet address on the chain" },
      "symbol": { "type": "string", "description": "Token symbol (optional)" }
    },
    "required": ["chain", "address"]
  }
}
```

---

### 3. query_deposit_address

Retrieves USDC and USDT deposit wallet addresses by blockchain address. For Solana chain, returns both USDC and USDT deposit addresses.

**When to Use**: When the user asks for deposit addresses or USDC/USDT recharge addresses.

#### Endpoint

```
POST /api/skills/query_deposit_address
```

#### Request Parameters

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `chain` | string | Yes | Blockchain name (e.g., solana, base) |
| `address` | string | Yes | Wallet address on the chain |
| `symbol` | string | No | Token symbol (optional; Solana returns both USDC and USDT) |

#### Request Example

```json
{
  "chain": "solana",
  "address": [REDACTED_SECRET]
}
```

#### Response Data

| Field | Type | Description |
|-------|------|-------------|
| `address` | string | Wallet address |
| `chain` | string | Blockchain network |
| `txHash` | string | Transaction hash (nullable) |
| `aPassAddress` | string | A-Pass NFT address |
| `depositUSDCWallet` | string | USDC deposit wallet address |
| `depositUSDTWallet` | string | USDT deposit wallet address |

#### Response Example

```json
{
  "code": "0000",
  "message": "success",
  "data": {
    "address": [REDACTED_SECRET],
    "chain": "solana",
    "txHash": null,
    "aPassAddress": [REDACTED_SECRET],
    "depositUSDCWallet": [REDACTED_SECRET],
    "depositUSDTWallet": [REDACTED_SECRET]
  }
}
```

#### LLM Tool Schema

```json
{
  "name": "query_deposit_address",
  "description": "Retrieve deposit wallet addresses for USDC and USDT by blockchain address. Use when user asks for deposit address, where to send USDC/USDT, or similar.",
  "parameters": {
    "type": "object",
    "properties": {
      "chain": { "type": "string", "description": "Blockchain (e.g., solana, base)" },
      "address": { "type": "string", "description": "Wallet address on the chain" },
      "symbol": { "type": "string", "description": "Token symbol (optional)" }
    },
    "required": ["chain", "address"]
  }
}
```

---

### 4. query_chain_config

Returns supported chain configuration for all networks: chain id, display name, block explorer, EVM flag, RPC URL, operational addresses, A-Pass address, and token lists.

**When to Use**: When the user asks about supported chains, which networks, token lists, RPC URLs, explorer links, or chain configuration.

#### Endpoint

```
GET/POST /api/skills/query_chain_config
```

#### Request

No request body. No parameters required. Supports both GET and POST.

#### Response Data

| Field | Type | Description |
|-------|------|-------------|
| `data.chains` | array | Array of chain configuration objects |

#### Chain Object (`chains[]`)

| Field | Type | Description |
|-------|------|-------------|
| `chain` | string | Chain key |
| `chain_id` | integer | Numeric chain id (e.g., -1 for Solana) |
| `chain_name` | string | Display name |
| `explorer` | string | Block explorer base URL |
| `is_evm` | boolean | Whether chain is EVM |
| `rpc_url` | string | RPC endpoint |
| `operator_address` | string | Operator address |
| `fee_pay_address` | string | Fee payer address |
| `fee_receive_address` | string | Fee receiver address |
| `rent_payer_address` | string | Rent payer (Solana; may be empty) |
| `apass_address` | string | A-Pass program or NFT address |
| `wallet_core` | string | Wallet core address (may be empty) |
| `tokens` | array | Configured tokens for this chain |

#### Token Object (`tokens[]`)

| Field | Type | Description |
|-------|------|-------------|
| `chain` | string | Chain key |
| `symbol` | string | Origin symbol |
| `a_symbol` | string | A-Token symbol |
| `token_address` | string | Token mint/contract address |
| `name` | string | Display name |
| `decimals` | integer | Decimals |
| `icon` | string | Icon URL |
| `token_category` | string | Category (e.g., token) |
| `access_core` | string | Access core (may be empty) |
| `deposit_gateway` | string | Deposit gateway (may be empty) |

#### Response Example

```json
{
  "code": "0000",
  "message": "ok",
  "data": {
    "chains": [
      {
        "chain": "solana",
        "chain_id": -1,
        "chain_name": "Solana",
        "explorer": "https://solscan.io/?cluster=devnet",
        "is_evm": false,
        "rpc_url": "https://solana-devnet.g.alchemy.com/v2/_ztkT79iUO-dFpkTNDBFB",
        "operator_address": [REDACTED_SECRET],
        "fee_pay_address": [REDACTED_SECRET],
        "fee_receive_address": [REDACTED_SECRET],
        "rent_payer_address": "",
        "apass_address": [REDACTED_SECRET],
        "wallet_core": "",
        "tokens": [
          {
            "chain": "solana",
            "symbol": "usdc",
            "a_symbol": "ausdc",
            "token_address": [REDACTED_SECRET],
            "name": "USDC",
            "decimals": 6,
            "icon": "https://images.cleanverse.com/app/token_icon/USDC.svg",
            "token_category": "token",
            "access_core": "",
            "deposit_gateway": ""
          }
        ]
      }
    ]
  }
}
```

#### LLM Tool Schema

```json
{
  "name": "query_chain_config",
  "description": "Get supported chain configuration for all networks: explorer, RPC, EVM flag, operational addresses, A-Pass address, and token lists. No parameters required.",
  "parameters": {
    "type": "object",
    "properties": {},
    "required": []
  }
}
```

---

### 5. query_deposit_institutions

Returns the list of institutions allowed for deposit (whitelist) grouped by origin token and A-Token pair.

**When to Use**: When the user asks about which institutions can deposit, deposit whitelist, supported custodians for USDT/USDC.

#### Endpoint

```
POST /api/skills/query_deposit_institutions
```

#### Request Parameters

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `chain` | string | Yes | Blockchain name (e.g., solana, base) |
| `symbol` | string | Yes | Token symbol (e.g., usdt, usdc) |

#### Request Example

```json
{
  "chain": "solana",
  "symbol": "usdt"
}
```

#### Response Data

| Field | Type | Description |
|-------|------|-------------|
| `chain` | string | Chain key (may be empty) |
| `token_whitelist` | array | Entries per origin/A-Token pair |

#### Token Whitelist Object (`token_whitelist[]`)

| Field | Type | Description |
|-------|------|-------------|
| `origin_symbol` | string | Origin token symbol |
| `origin_token_address` | string | Origin token address |
| `atoken_symbol` | string | A-Token symbol |
| `atoken_address` | string | A-Token address |
| `whitelist` | array | Whitelisted institutions |

#### Institution Object (`whitelist[]`)

| Field | Type | Description |
|-------|------|-------------|
| `service_name` | string | Service display name |
| `entity_name` | string | Legal entity name |
| `category` | string | Business category |
| `icon` | string | Icon URL |

#### Response Example

```json
{
  "code": "0000",
  "message": "ok",
  "data": {
    "chain": "",
    "token_whitelist": [
      {
        "origin_symbol": "usdt",
        "origin_token_address": [REDACTED_SECRET],
        "atoken_symbol": "ausdt",
        "atoken_address": [REDACTED_SECRET],
        "whitelist": [
          {
            "service_name": "Anchorage Digital",
            "entity_name": "Anchorage Digital NY, LLC",
            "category": "Infrastructure",
            "icon": "https://images.cleanverse.com/member/ANCHORAGE DIGITAL SINGAPORE Pte. Ltd..png"
          }
        ]
      }
    ]
  }
}
```

#### LLM Tool Schema

```json
{
  "name": "query_deposit_institutions",
  "description": "Get the list of institutions whitelisted for token deposit for the given chain and token symbol. Use when user asks which partners or custodians can deposit, or for deposit whitelist information.",
  "parameters": {
    "type": "object",
    "properties": {
      "chain": { "type": "string", "description": "Blockchain (e.g., solana, base)" },
      "symbol": { "type": "string", "description": "Token symbol (e.g., usdt, usdc)" }
    },
    "required": ["chain", "symbol"]
  }
}
```

---

### 6. register_data

Registers (writes) a user wallet address for the given chain and token. Returns the user address and associated deposit address.

**When to Use**: When the user wants to save, register, or bind their wallet for deposits, or submit a user address to obtain a Cleanverse deposit address.

#### Endpoint

```
POST /api/skills/register_data
```

#### Request Parameters

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `chain` | string | Yes | Blockchain name (e.g., base) |
| `symbol` | string | Yes | Token symbol (e.g., usdc) |
| `address` | string | Yes | User wallet address |

#### Request Example

```json
{
  "chain": "base",
  "symbol": "usdc",
  "address": [REDACTED_SECRET]
}
```

#### Response Data

| Field | Type | Description |
|-------|------|-------------|
| `user_address` | string | Registered user wallet address |
| `deposit_address` | string | Mapped Cleanverse deposit address |
| `chain` | string | Blockchain |
| `symbol` | string | Token symbol (may be empty string) |

#### Response Example

```json
{
  "code": "0000",
  "message": "ok",
  "data": {
    "user_address": [REDACTED_SECRET],
    "deposit_address": [REDACTED_SECRET],
    "chain": "base",
    "symbol": ""
  }
}
```

#### LLM Tool Schema

```json
{
  "name": "register_data",
  "description": "Register or write a user wallet address for a chain and token; returns user_address and deposit_address. Use when user wants to bind or save their address for deposits.",
  "parameters": {
    "type": "object",
    "properties": {
      "chain": { "type": "string", "description": "Blockchain (e.g., base)" },
      "symbol": { "type": "string", "description": "Token symbol (e.g., usdc)" },
      "address": { "type": "string", "description": "User wallet address" }
    },
    "required": ["chain", "symbol", "address"]
  }
}
```

---

### 7. query_user

Queries a registered user by chain, token symbol, and address. Returns deposit address, deposit status, account status, and blacklist reason when applicable.

**When to Use**: When the user asks to check their registration, deposit address status, if they are blacklisted, or to look up an existing user + token mapping.

#### Endpoint

```
POST /api/skills/query_user
```

#### Request Parameters

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `chain` | string | Yes | Blockchain name (e.g., base) |
| `symbol` | string | Yes | Token symbol (e.g., usdc) |
| `address` | string | Yes | User wallet address |

#### Request Example

```json
{
  "chain": "base",
  "symbol": "usdc",
  "address": [REDACTED_SECRET]
}
```

#### Response Data

| Field | Type | Description |
|-------|------|-------------|
| `chain` | string | Blockchain |
| `symbol` | string | Token symbol (may be empty string) |
| `user_address` | string | User wallet address |
| `deposit_address` | string | Deposit address |
| `deposit_address_status` | string | Deposit address status (may be empty) |
| `status` | integer | User/account status (e.g., 0) |
| `blacklist_reason` | string | Blacklist reason if applicable (may be empty) |

#### Response Example

```json
{
  "code": "0000",
  "message": "ok",
  "data": {
    "chain": "base",
    "symbol": "",
    "user_address": [REDACTED_SECRET],
    "deposit_address": [REDACTED_SECRET],
    "deposit_address_status": "",
    "status": 0,
    "blacklist_reason": ""
  }
}
```

#### LLM Tool Schema

```json
{
  "name": "query_user",
  "description": "Query registered user info: deposit address, deposit status, account status, blacklist reason. Use after register_data or when user asks about their registration or deposit mapping.",
  "parameters": {
    "type": "object",
    "properties": {
      "chain": { "type": "string", "description": "Blockchain (e.g., base)" },
      "symbol": { "type": "string", "description": "Token symbol (e.g., usdc)" },
      "address": { "type": "string", "description": "User wallet address" }
    },
    "required": ["chain", "symbol", "address"]
  }
}
```

---

## Response Codes

| Code | Description |
|------|-------------|
| `0000` | Success |
| `0001` | Parameter error |
| `0002` | General failure |

---

## Appendix: Usage Examples

### Example 1: Get A-Pass Registration Link

```
User: How do I register for A-Pass?
Assistant: [Call get_magiclink]
Assistant: Please visit the following link to register: {register_url}
```

### Example 2: Query A-Pass Status

```
User: Check A-Pass status for this address: 0x121C439ff356e806C3da108eE794c4Dd485984d3 (Base chain)
Assistant: [Call query_apass, parameters: chain="base", address=[REDACTED_SECRET]]
Assistant: A-Pass information for this address: Tier 4, status active, expiration time...
```

### Example 3: Query Deposit Address

```
User: What is the USDC deposit address for Solana address 9wF7Yp8MZk2J6qX4R5GQKxE3P7H8YyNQ1JZVfA6mB2c?
Assistant: [Call query_deposit_address, parameters: chain="solana", address=[REDACTED_SECRET]]
Assistant: Your USDC deposit address is: 2q2d2L1eZEhgVFv2nLz8hWbPPWGP7aXGkjD8uZd7mDGV
```

### Example 4: Query Chain Configuration

```
User: What chains and tokens are supported in Cleanverse?
Assistant: [Call query_chain_config]
Assistant: Cleanverse supports the following chains:
- Solana (non-EVM): USDC
- Base (EVM): USDC
- Ethereum (EVM): USDC, USDT
- Polygon (EVM): USDC, USDT
- Arbitrum (EVM): USDC, USDT
```

### Example 5: Query Deposit Institutions

```
User: Which institutions can I deposit USDT from on Base chain?
Assistant: [Call query_deposit_institutions, parameters: chain="base", symbol="usdt"]
Assistant: The following institutions support USDT deposits on Base:
- Anchorage Digital (Anchorage Digital NY, LLC)
```

### Example 6: Register User Address

```
User: I want to register my wallet for USDC deposits on Base
Assistant: [Call register_data, parameters: chain="base", symbol="usdc", address="0x543b..."]
Assistant: Your wallet has been registered. Your deposit address is: 0xd771...
```

### Example 7: Query User Registration Status

```
User: Check my registration status for USDC on Base
Assistant: [Call query_user, parameters: chain="base", symbol="usdc", address="0x543b..."]
Assistant: Your registration info:
- User Address: 0x543b...
- Deposit Address: 0xd771...
- Status: Active
```


path: references/access_core.md
content: # Access Core Contract ABI

access core contract abi file

```json
[
  {
    "type": "function",
    "name": "withdraw",
    "inputs": [
      {
        "name": "aToken",
        "type": "address",
        "internalType": "address"
      },
      {
        "name": "amount",
        "type": "uint256",
        "internalType": "uint256"
      },
      {
        "name": "recipient",
        "type": "address",
        "internalType": "address"
      }
    ],
    "outputs": [],
    "stateMutability": "nonpayable"
  },
  {
    "type": "event",
    "name": "Withdraw",
    "inputs": [
      {
        "name": "aToken",
        "type": "address",
        "indexed": true,
        "internalType": "address"
      },
      {
        "name": "originToken",
        "type": "address",
        "indexed": true,
        "internalType": "address"
      },
      {
        "name": "amount",
        "type": "uint256",
        "indexed": false,
        "internalType": "uint256"
      },
      {
        "name": "recipient",
        "type": "address",
        "indexed": true,
        "internalType": "address"
      },
      {
        "name": "data",
        "type": "bytes32",
        "indexed": false,
        "internalType": "bytes32"
      }
    ],
    "anonymous": false
  }
]
```


path: references/quick-api-map.md
content: # Quick API map

Use this file first when the task is operational and you want the shortest path to the right API.

## get_magiclink

Use when the user wants to register, sign up, or get started with Cleanverse / ClevrPay.

- Required params: none
- Returns: registration URL
- Common phrasing:
  - how do I sign up
  - how do I get started
  - how do I get A-Pass
  - send me the registration link

## query_apass

Use when the user wants to check eligibility / status for a wallet.

- Required params: `chain`, `address`
- Optional: `symbol`
- Returns: tier, expiration, state, group-related data
- Common phrasing:
  - check my payment eligibility
  - is this wallet verified
  - does this address have A-Pass
  - can this wallet receive compliant payment

## query_deposit_address

Use when the user wants to know where to send supported funds.

- Required params: `chain`, `address`
- Optional: `symbol`
- Returns: deposit wallet address(es)
- Common phrasing:
  - where do I send USDC
  - what is my deposit address
  - where can I deposit funds
  - how do I move clean funds into Cleanverse

## query_deposit_institutions

Use when the user wants to know which institutions / sources are allowed for deposit.

- Required params: `chain`, `symbol`
- Returns: deposit whitelist
- Common phrasing:
  - which institutions can deposit
  - what custodians are allowed
  - what is the whitelist source for deposit

## query_chain_config

Use when the user asks about support coverage or when any static doc may be stale.

- Required params: none
- Returns: live chain/token/access config
- Common phrasing:
  - what chains are supported
  - what tokens are supported
  - does Cleanverse support this network

## query_user

Use when the user wants to check whether a wallet is already registered or mapped.

- Required params: `chain`, `symbol`, `address`
- Returns: deposit mapping and status
- Common phrasing:
  - is my wallet registered
  - check my mapping
  - what deposit address is linked to my wallet

## register_data

Use when the wallet needs to be registered / mapped for a chain and token.

- Required params: `chain`, `symbol`, `address`
- Returns: user address and deposit address mapping
- Common phrasing:
  - register my wallet
  - bind my address
  - set up my deposit mapping

## Decision shortcut

- signup / registration link -> `get_magiclink`
- check qualification / status -> `query_apass`
- get deposit address -> `query_deposit_address`
- check allowed deposit source -> `query_deposit_institutions`
- confirm supported chains/tokens -> `query_chain_config`
- check existing registration -> `query_user`
- create registration mapping -> `register_data`


path: references/use-cases.md
content: # Use cases

Use these examples to help agents and humans discover ClevrPay through real-world payment intent, not only internal terminology.

## 1. Global supplier payment

An AI agent negotiates with an overseas supplier, confirms commercial terms, and then settles through ClevrPay so the payment happens between verified counterparties rather than unknown wallets.

Why ClevrPay fits:

- trusted global payment
- better counterparty confidence
- low-cost cross-border settlement
- more suitable for meaningful-value commercial payment than anonymous wallet transfer

## 2. Global product purchase / sourcing

An agent finds inventory across borders, compares quotes, and completes payment for the chosen supplier.

Why ClevrPay fits:

- supports global decentralized purchasing with trusted settlement
- useful when the buyer wants cleaner payment flow and clearer eligibility than open wallet-to-wallet transfer

## 3. Travel booking

An agent books flights, hotels, or travel packages for a user or business and then completes payment using a verified payment flow.

Why ClevrPay fits:

- payment trust matters because the transaction is tied to a real booking or reservation
- useful when paying counterparties globally with clearer eligibility and cleaner circulation logic

## 4. Ride hailing / local services

An agent arranges airport pickup, local transport, or service fulfillment and then pays the provider.

Why ClevrPay fits:

- a practical example of real-world service payment rather than speculative transfer
- relevant when the user wants payment to flow through a more trusted, verified path

## 5. Remote auction / bidding

An agent bids in a remote auction or negotiates for a scarce item, wins the bid, and then needs to settle remotely.

Why ClevrPay fits:

- settlement confidence matters because the transaction value may be significant
- verified-counterparty framing is more compelling than anonymous transfer for this use case

## 6. Decentralized crypto trading with cleaner settlement boundaries

An agent sources liquidity, compares venues, or manages execution strategy, but settlement still needs cleaner participation boundaries.

Why ClevrPay fits:

- useful where the user cares about cleaner funds circulation and trusted counterparties
- especially relevant when the concern is not just execution, but who is participating in the payment flow

## 7. Decentralized investing / allocation

An agent helps allocate capital into opportunities, secondary deals, or structured participation flows that require more trusted settlement conditions.

Why ClevrPay fits:

- more relevant for meaningful-value capital movement than for tiny micropayments
- can be described as trusted payment rails for non-trivial decentralized investment flows

## 8. Agent-to-business settlement

An AI agent completes a business task — sourcing, negotiation, procurement, matching, or execution — and then needs to settle a real commercial obligation.

Why ClevrPay fits:

- this is the clearest expression of agent commerce with trusted payment
- the agent can do the commerce work; ClevrPay provides the reliable settlement layer

## 9. Cross-border professional services

An agent helps procure legal, design, engineering, consulting, or data services from another jurisdiction and then pays the service provider.

Why ClevrPay fits:

- higher trust and cleaner counterparty/payment framing than open anonymous transfer
- suited to real economic activity across borders

## 10. Treasury or partner settlement

A team needs to pay a partner, supplier, operator, or contributor in another region without relying on multiple intermediaries.

Why ClevrPay fits:

- global low-cost payment rails
- verified-counterparty logic
- cleaner funds movement narrative

## Positioning rule

Start from the human problem:

- global payment
- trusted payment
- clean-funds payment
- verified-counterparty payment
- low-cost cross-border settlement
- AI agent business payment

Then map to product primitives:

- Access Pass (A-Pass)
- Access Token (A-Token)
- deposit address / whitelist / registration / supported-chain workflow


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (HIGH)