@agentwallex/openclaw 0.0.1

package/README.md

@@ -0,0 +1,201 @@
+# @agentwallex/openclaw
+
+OpenClaw plugin for [AgentWallex](https://agentwallex.com) — gives AI agents the ability to send USDC payments, check balances, and query transactions.
+
+## Quick Start
+
+### 1. Install the plugin
+
+```bash
+openclaw plugins install @agentwallex/openclaw
+```
+
+### 2. Set up via conversation
+
+Tell your AI agent:
+
+```
+"Set up AgentWallex"
+```
+
+The agent will guide you through:
+
+1. Opening the [AgentWallex Dashboard](https://app.agentwallex.com)
+2. Signing in with Google
+3. Creating an API key (starts with `awx_`)
+4. Copying your Agent ID
+5. Pasting the credentials back — they're validated and saved locally
+
+That's it — zero config files needed. Credentials are stored at `~/.openclaw/agentwallex/config.json` with owner-only permissions.
+
+### 3. Use it
+
+Your agent now has payment tools available. Just ask naturally:
+
+```
+"Check my USDC balance"
+"Send 5 USDC to 0xAbC...123"
+"What's the status of transaction tx-abc123?"
+```
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `agentwallex_setup` | Check configuration status and get setup instructions |
+| `agentwallex_configure` | Validate and save API credentials |
+| `agentwallex_create_agent` | Create a new AI agent with its own wallet |
+| `agentwallex_list_agents` | List all agents and their status |
+| `agentwallex_create_wallet` | Get or create a deposit address for the agent |
+| `agentwallex_pay` | Send a USDC payment to a recipient address |
+| `agentwallex_check_balance` | Check the agent's USDC balance |
+| `agentwallex_tx_status` | Query the status of a transaction |
+
+## Usage Examples
+
+Once the plugin is set up, you can interact with your agent using natural language. Here are some common scenarios:
+
+### Create an Agent
+
+```
+You: Create a new agent called "payment-bot" on base chain
+Agent: Agent created successfully.
+       Agent ID: agent-a1b2c3d4
+       Name: payment-bot
+       Chain: base
+       Status: active
+```
+
+### List Agents
+
+```
+You: How many agents do I have?
+Agent: You have 3 agents:
+       1. payment-bot (agent-a1b2) — base — active
+       2. data-fetcher (agent-c3d4) — base-sepolia — active
+       3. old-bot (agent-e5f6) — base — inactive
+```
+
+### Check Balance
+
+```
+You: What's my current USDC balance?
+Agent: Your available USDC balance on base is 150.00 USDC.
+```
+
+### Send a Payment
+
+```
+You: Send 25 USDC to 0xAbCdEf1234567890AbCdEf1234567890AbCdEf12
+Agent: I'll send 25 USDC to that address.
+      Transaction created: tx-a1b2c3d4
+      Status: pending
+      I'll check back on the status shortly.
+```
+
+### Check Transaction Status
+
+```
+You: What's the status of my last payment?
+Agent: Transaction tx-a1b2c3d4:
+       Status: confirmed
+       Tx Hash: 0x7f8e...3a2b
+       Confirmed at: 2025-03-06T12:34:56Z
+```
+
+### Create a Wallet
+
+```
+You: Set up a wallet on base-sepolia for testing
+Agent: Wallet created on base-sepolia.
+       Address: 0x1234...5678
+       You can deposit testnet USDC to this address.
+```
+
+### Multi-step Workflow
+
+```
+You: Check if I have enough balance, then send 10 USDC to 0xRecipient as payment for the API service
+
+Agent: Let me check your balance first.
+       Available: 150.00 USDC on base — sufficient.
+       Sending 10 USDC to 0xRecipient...
+       Transaction created: tx-e5f6g7h8
+       Status: pending
+       I'll monitor this and let you know when it confirms.
+```
+
+### Error Handling
+
+```
+You: Send 99999 USDC to 0xRecipient
+Agent: I checked your balance first — you only have 150.00 USDC available,
+       which is insufficient for a 99999 USDC transfer.
+       Would you like to send a smaller amount?
+```
+
+## For Developers
+
+If you want to use the tool functions directly in code (without OpenClaw):
+
+```typescript
+import { AgentWallex, checkBalance, pay } from '@agentwallex/openclaw';
+
+const client = new AgentWallex({ apiKey: 'awx_...' });
+const agentId = 'your-agent-id';
+
+// Check balance
+const balance = await checkBalance(client, agentId, { chain: 'base' });
+console.log(balance.available); // "100.50"
+
+// Send payment
+const tx = await pay(client, agentId, {
+  to: '0xRecipientAddress',
+  amount: '10.00',
+});
+console.log(tx.transaction_id); // "tx-abc123"
+```
+
+### Install as npm dependency
+
+```bash
+npm install @agentwallex/openclaw
+# or
+pnpm add @agentwallex/openclaw
+```
+
+### Exports
+
+```typescript
+// OpenClaw plugin entry
+import register from '@agentwallex/openclaw';
+
+// Tool functions (for direct use)
+import { createAgent, listAgents, createWallet, pay, checkBalance, txStatus } from '@agentwallex/openclaw';
+
+// Static tool schema (for custom integrations)
+import { openClawToolSchema } from '@agentwallex/openclaw';
+
+// Local credential store
+import { loadConfig, saveConfig, isConfigured } from '@agentwallex/openclaw';
+
+// SDK client (re-exported from @agentwallex/sdk)
+import { AgentWallex } from '@agentwallex/openclaw';
+```
+
+## Sandbox Testing
+
+To test against the sandbox environment, pass `sandbox: true` when configuring:
+
+```
+"Configure AgentWallex with my sandbox API key awx_sandbox_xxx and agent ID agent-123, using sandbox mode"
+```
+
+Sandbox transactions use testnet tokens and don't cost real money.
+
+## Links
+
+- [AgentWallex Dashboard](https://app.agentwallex.com)
+- [AgentWallex Documentation](https://docs.agentwallex.com)
+- [SDK Package (`@agentwallex/sdk`)](https://www.npmjs.com/package/@agentwallex/sdk)
+- [OpenClaw Documentation](https://docs.openclaw.ai)