Master Keys

Master keys allow you to programmatically create and manage agents. This is useful for platforms that need to create wallets for multiple users or AI agents.

Overview

While the device flow is great for interactive applications, master keys enable:

Programmatic agent creation without user interaction
Platform integration for multi-tenant applications
Automated deployment of AI agents with wallets

Master Key Security

Master keys are powerful credentials. They can create agents and API keys on your behalf. Store them securely and never expose them in client-side code.

Creating a Master Key

Master keys are created via the device flow with a special flag:

import { SpongeAdmin } from "@spongewallet/sdk";
 
// This initiates device flow for a master key
const admin = await SpongeAdmin.connect();

Or request a master key explicitly:

import { SpongeWallet } from "@spongewallet/sdk";
 
const wallet = await SpongeWallet.connect({
  keyType: "master"
});

Using SpongeAdmin

Once you have a master key, use SpongeAdmin to manage agents:

import { SpongeAdmin } from "@spongewallet/sdk";
 
// Initialize with master key
const admin = await SpongeAdmin.fromApiKey("master_xxx_...");
 
// Or from environment variable
// SPONGE_MASTER_KEY=master_xxx_...
const admin = await SpongeAdmin.connect();

Creating Agents

const agent = await admin.createAgent({
  name: "Trading Bot Alpha",
  description: "Automated trading agent for DeFi",
  testnet: true // Create test agent
});
 
console.log(agent);
// {
//   id: "agent_abc123",
//   name: "Trading Bot Alpha",
//   apiKey: "sponge_test_xyz...",  // Only shown on creation
//   wallets: {
//     evm: "0x...",
//     solana: "7nYB..."
//   }
// }

Agent Options

const agent = await admin.createAgent({
  name: "My Agent",
  description: "Agent description",
  testnet: true,
 
  // Optional spending limits
  dailySpendingLimit: "100.0",   // USD
  weeklySpendingLimit: "500.0",
  monthlySpendingLimit: "1000.0",
 
  // Optional metadata
  metadata: {
    customField: "value",
    environment: "production"
  }
});

Listing Agents

const agents = await admin.listAgents({
  includeBalances: true,
  testMode: true
});
 
// [
//   {
//     id: "agent_abc123",
//     name: "Trading Bot Alpha",
//     status: "active",
//     balanceUsdValue: "150.00",
//     createdAt: "2024-01-15T10:00:00Z"
//   },
//   ...
// ]

Getting an Agent

const agent = await admin.getAgent("agent_abc123");
 
console.log(agent);
// {
//   id: "agent_abc123",
//   name: "Trading Bot Alpha",
//   status: "active",
//   wallets: [...],
//   spendingLimits: [...],
//   createdAt: "2024-01-15T10:00:00Z"
// }

Managing Agent Wallets

// Get wallets for an agent
const wallets = await admin.getAgentWallets("agent_abc123");
 
// Get balances
const balances = await admin.getAgentBalances("agent_abc123");

Using the Agent API Key

After creating an agent, use its API key with SpongeWallet:

// Create agent with admin
const agent = await admin.createAgent({
  name: "My Bot",
  testnet: true
});
 
// Use agent's API key
const wallet = await SpongeWallet.fromApiKey(agent.apiKey);
 
// Now operate as this agent
const balances = await wallet.getBalances();

Setting Spending Limits

Control how much an agent can spend:

await admin.setSpendingLimit("agent_abc123", {
  type: "daily",
  amount: "100.0",
  currency: "USD"
});
 
await admin.setSpendingLimit("agent_abc123", {
  type: "per_transaction",
  amount: "25.0",
  currency: "USD"
});

Limit Types

Type	Description
`per_transaction`	Maximum per single transaction
`per_minute`	Rolling 1-minute limit
`hourly`	Rolling 1-hour limit
`daily`	Rolling 24-hour limit
`weekly`	Rolling 7-day limit
`monthly`	Rolling 30-day limit

Managing Allowlists

Restrict which addresses an agent can send to:

// Add address to allowlist
await admin.addToAllowlist("agent_abc123", {
  chain: "base",
  address: "0xTrustedAddress",
  label: "Treasury"
});
 
// List allowlist
const allowlist = await admin.getAgentAllowlist("agent_abc123");
 
// Remove from allowlist
await admin.removeFromAllowlist("agent_abc123", "allowlist_item_id");

Rotating API Keys

Rotate an agent's API key:

const newKey = await admin.rotateAgentKey("agent_abc123");
 
console.log(newKey);
// {
//   apiKey: "sponge_test_newkey...",
//   previousKeyRevoked: true
// }

Pausing and Resuming Agents

// Pause an agent (disables all operations)
await admin.pauseAgent("agent_abc123");
 
// Resume an agent
await admin.resumeAgent("agent_abc123");
 
// Check status
const agent = await admin.getAgent("agent_abc123");
console.log(agent.status); // "paused" or "active"

Deleting Agents

// Delete an agent (cannot be undone)
await admin.deleteAgent("agent_abc123");

Agent Deletion

Deleting an agent revokes all API keys and removes access to wallets. Make sure to withdraw any funds before deletion.

Audit Logs

View agent activity:

const logs = await admin.getAgentAuditLogs("agent_abc123", {
  limit: 50
});
 
// [
//   {
//     action: "transaction.submitted",
//     timestamp: "2024-01-15T10:30:00Z",
//     metadata: { hash: "0x...", amount: "10.0", currency: "USDC" }
//   },
//   ...
// ]

Master Key Scopes

Master keys support granular scopes:

Scope	Description
`agents:create`	Create new agents
`agents:read`	List and view agents
`agents:update`	Update agent settings
`agents:delete`	Delete agents

Best Practices

Store master keys in secrets managers (AWS Secrets Manager, HashiCorp Vault, etc.)
Use separate master keys for development and production
Set spending limits on all agents by default
Monitor audit logs for suspicious activity
Rotate master keys periodically