@mixrpay/agent-sdk 0.8.6 → 0.8.9

package/README.md

@@ -2,15 +2,71 @@
 
 Enable AI agents to make payments to MixrPay-powered APIs.
 
+## Getting Started: Claim an Access Code
+
+Agents get spending authorization by claiming an **Access Code** from a human wallet owner.
+
+### Step 1: Human Creates Access Code
+
+The human logs in at [mixrpay.com/manage/invites](https://www.mixrpay.com/manage/invites), deposits funds, and creates an Access Code (e.g., `mixr-abc123`) with a budget.
+
+### Step 2: Agent Claims the Access Code
+
+```typescript
+import { AgentWallet } from '@mixrpay/agent-sdk';
+
+// Claim the Access Code to get your session key
+const result = await AgentWallet.claimInvite({
+  inviteCode: 'mixr-abc123',              // From the human
+  privateKey: process.env.AGENT_WALLET_KEY as `0x${string}`,
+});
+
+// IMPORTANT: Save this immediately — shown ONCE, cannot be recovered!
+console.log('Session Key:', result.sessionKey);  // sk_live_xxx
+console.log('Budget:', result.limits.budgetUsd);
+console.log('Invited by:', result.inviterName);
+```
+
+### Step 3: Use the Session Key
+
+```typescript
+const wallet = new AgentWallet({
+  sessionKey: result.sessionKey,  // or process.env.MIXRPAY_SESSION_KEY
+});
+
+// All spending is authorized from the human's wallet
+const response = await wallet.fetch('https://api.example.com/paid-endpoint');
+```
+
+## Understanding Wallet Addresses
+
+When you claim an Access Code, two addresses are involved:
+
+| Address | What it is | Purpose |
+|---------|-----------|---------|
+| `info.address` | Session key's derived address | Used for signing requests |
+| `info.walletAddress` | Human's funded wallet | Where funds are charged FROM |
+
+**Verify which wallet you're spending from:**
+
+```typescript
+const info = await wallet.getSessionKeyInfo();
+console.log('Session key:', info.address);        // Your signing key
+console.log('Spending from:', info.walletAddress); // Human's wallet (funding source)
+console.log('Budget remaining:', info.limits.totalUsd);
+```
+
+This is important: your session key authorizes spending from the **human's wallet**, not your own external wallet. The human controls the budget and can revoke access at any time.
+
 ## Important: Session Key Security
 
 Your session key (`sk_live_...`) is a **private key**. Treat it like a password:
 
-- **Save it immediately** when you receive it (from `claimInvite()` or dashboard)
+- **Save it immediately** when you receive it (from `claimInvite()`)
 - **Store it securely** (environment variable, secrets manager)
 - **Never commit it** to version control
 - **Never log it** to console or files
-- **It cannot be recovered** if lost - you will need a new invite
+- **It cannot be recovered** if lost - you will need a new Access Code
 
 The session key is shown **only once** when claimed. MixrPay does not store it.
 
@@ -39,8 +95,6 @@ const response = await wallet.callMerchantApi({
 const data = await response.json();
 ```
 
-Get session keys at [mixrpay.com/wallet/sessions](https://www.mixrpay.com/wallet/sessions).
-
 ## Core Methods
 
 ```typescript