@mixrpay/agent-sdk 0.8.6 → 0.8.7

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

package/dist/index.cjs

@@ -532,7 +532,7 @@ function getAmountUsd(requirements) {
 }
 
 // src/agent-wallet.ts
-var SDK_VERSION = "0.8.5";
+var SDK_VERSION = "0.8.7";
 var DEFAULT_BASE_URL = process.env.MIXRPAY_BASE_URL || "https://www.mixrpay.com";
 var DEFAULT_TIMEOUT = 3e4;
 var NETWORKS = {
@@ -1707,6 +1707,7 @@ var AgentWallet = class {
         const data = await response.json();
         this.sessionKeyInfo = {
           address: this.sessionKey.address,
+          walletAddress: data.wallet_address ?? data.walletAddress ?? null,
           isValid: data.is_valid ?? data.isValid ?? true,
           limits: {
             perTxUsd: data.per_tx_limit_usd ?? data.perTxLimitUsd ?? null,
@@ -1731,6 +1732,7 @@ var AgentWallet = class {
     }
     return {
       address: this.sessionKey.address,
+      walletAddress: null,
       isValid: true,
       limits: { perTxUsd: null, dailyUsd: null, totalUsd: null },
       usage: { todayUsd: this.totalSpentUsd, totalUsd: this.totalSpentUsd, txCount: this.payments.length },

package/dist/index.d.cts

@@ -129,8 +129,14 @@ interface PaymentEvent {
  * Information about a session key.
  */
 interface SessionKeyInfo {
-    /** The session key's address (derived public key) */
+    /** The session key's derived address (used for signing requests) */
     address: string;
+    /**
+     * The wallet address this session key is authorized to spend from.
+     * This is the human's funded wallet, NOT your agent's external wallet.
+     * All charges are deducted from this wallet.
+     */
+    walletAddress: string | null;
     /** Whether the session key is currently valid */
     isValid: boolean;
     /** Spending limits configured for this session key */
@@ -379,7 +385,7 @@ interface SessionStats {
  */
 
 /** Current SDK version */
-declare const SDK_VERSION = "0.8.5";
+declare const SDK_VERSION = "0.8.7";
 /** Supported networks */
 declare const NETWORKS: {
     readonly BASE_MAINNET: {

package/dist/index.d.ts

@@ -129,8 +129,14 @@ interface PaymentEvent {
  * Information about a session key.
  */
 interface SessionKeyInfo {
-    /** The session key's address (derived public key) */
+    /** The session key's derived address (used for signing requests) */
     address: string;
+    /**
+     * The wallet address this session key is authorized to spend from.
+     * This is the human's funded wallet, NOT your agent's external wallet.
+     * All charges are deducted from this wallet.
+     */
+    walletAddress: string | null;
     /** Whether the session key is currently valid */
     isValid: boolean;
     /** Spending limits configured for this session key */
@@ -379,7 +385,7 @@ interface SessionStats {
  */
 
 /** Current SDK version */
-declare const SDK_VERSION = "0.8.5";
+declare const SDK_VERSION = "0.8.7";
 /** Supported networks */
 declare const NETWORKS: {
     readonly BASE_MAINNET: {

package/dist/index.js

@@ -495,7 +495,7 @@ function getAmountUsd(requirements) {
 }
 
 // src/agent-wallet.ts
-var SDK_VERSION = "0.8.5";
+var SDK_VERSION = "0.8.7";
 var DEFAULT_BASE_URL = process.env.MIXRPAY_BASE_URL || "https://www.mixrpay.com";
 var DEFAULT_TIMEOUT = 3e4;
 var NETWORKS = {
@@ -1670,6 +1670,7 @@ var AgentWallet = class {
         const data = await response.json();
         this.sessionKeyInfo = {
           address: this.sessionKey.address,
+          walletAddress: data.wallet_address ?? data.walletAddress ?? null,
           isValid: data.is_valid ?? data.isValid ?? true,
           limits: {
             perTxUsd: data.per_tx_limit_usd ?? data.perTxLimitUsd ?? null,
@@ -1694,6 +1695,7 @@ var AgentWallet = class {
     }
     return {
       address: this.sessionKey.address,
+      walletAddress: null,
       isValid: true,
       limits: { perTxUsd: null, dailyUsd: null, totalUsd: null },
       usage: { todayUsd: this.totalSpentUsd, totalUsd: this.totalSpentUsd, txCount: this.payments.length },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mixrpay/agent-sdk",
-  "version": "0.8.6",
+  "version": "0.8.7",
   "description": "MixrPay Agent SDK - Enable AI agents to make x402 payments with session keys",
   "type": "module",
   "main": "./dist/index.js",