Authentication

Sponge uses API keys for authentication. There are two ways to obtain keys: the device flow (for interactive apps) and master keys (for programmatic agent creation).

Device Flow

The device flow is the recommended way to authenticate interactive applications. It follows the OAuth 2.0 Device Authorization Grant (RFC 8628).

Initiate Authorization

When you call connect(), the SDK initiates the device flow:

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

This displays a URL and code for the user to authorize.

User Authorization

The user visits the verification URL and enters the code. They can then approve or deny the request.

Token Exchange

Once approved, the SDK automatically exchanges the device code for an API key. The key is stored locally for future use.

Device Flow Options

const wallet = await SpongeWallet.connect({
  // Request test key (testnets only) or live key (mainnets only)
  testnet: true,
 
  // Custom agent name (shown in dashboard)
  agentName: "My Trading Bot",
 
  // Custom callback for displaying the verification URL
  onVerification: ({ verificationUri, userCode }) => {
    console.log(`Visit ${verificationUri} and enter code: ${userCode}`);
  }
});

API Key Types

Key Scoping

API keys are strictly scoped to either test or live environments. A test key cannot access mainnets, and a live key cannot access testnets.

Key Type	Prefix	Chains	Purpose
Test	`sponge_test_`	Testnets only	Development and testing
Live	`sponge_live_`	Mainnets only	Production use

Test Keys

Test keys can only access testnet chains:

sepolia - Ethereum Sepolia
base-sepolia - Base Sepolia
solana-devnet - Solana Devnet
tempo - Tempo testnet

Live Keys

Live keys can only access mainnet chains:

ethereum - Ethereum Mainnet
base - Base Mainnet
solana - Solana Mainnet

Manual API Key Usage

If you already have an API key, you can use it directly:

const wallet = await SpongeWallet.fromApiKey("sponge_test_...");
 
// Or set via environment variable
// SPONGE_API_KEY=sponge_test_...
const wallet = await SpongeWallet.connect();

Credential Storage

By default, the SDK stores credentials in:

macOS: ~/Library/Application Support/sponge/credentials.json
Linux: ~/.config/sponge/credentials.json
Windows: %APPDATA%\sponge\credentials.json

Custom Storage

You can provide custom credential storage:

const wallet = await SpongeWallet.connect({
  credentialStorage: {
    async get() {
      // Return stored credentials or null
      return await myDatabase.getCredentials();
    },
    async set(credentials) {
      // Store credentials
      await myDatabase.setCredentials(credentials);
    },
    async delete() {
      // Clear credentials
      await myDatabase.deleteCredentials();
    }
  }
});

Scopes

API keys have associated scopes that control what operations are permitted:

Scope	Description
`wallet:read`	Read wallet addresses and balances
`wallet:write`	Create and manage wallets
`transaction:read`	View transaction history
`transaction:sign`	Sign transactions
`transaction:write`	Submit transactions
`spending:read`	View spending limits
`flow:execute`	Execute automated flows
`payment:read`	Read payment methods
`payment:decrypt`	Decrypt stored cards
`payment:write`	Update payment records

const wallet = await SpongeWallet.connect();
 
// Check if authenticated
if (wallet.isAuthenticated()) {
  console.log("Authenticated as:", wallet.agentId);
}

Clearing Credentials

// Clear stored credentials and disconnect
await wallet.disconnect();

Refreshing Credentials

The SDK automatically refreshes credentials when needed. You can force a refresh:

await wallet.refresh();

Security Best Practices

Never Commit API Keys

Never commit API keys to version control. Use environment variables or secure credential storage.

Use environment variables for API keys in production
Rotate keys regularly using the dashboard
Use test keys during development
Set spending limits to cap maximum transaction amounts
Configure allowlists to restrict destination addresses