sonnet-protocol-sdk

Sonnet Protocol SDK

Launch AI agents with built-in X402 micropayments

Overview

Sonnet Protocol provides a developer SDK for launching custom AI agents with built-in payment infrastructure. Developers can brand their agents, add custom functionality, and earn 80% of payment revenue.

Features

Two Operating Modes

1. Test Mode - $0.025/prompt

• Single whitelisted wallet for development/testing
• Cheaper pricing for testing agents
• Perfect for development and debugging
• Limited to ONE wallet address per developer

2. Production Mode - $0.05/prompt

• Unlimited wallets can use your agent
• Standard production pricing
• Full public deployment
• Developer earns 80% of all payments

Revenue Split

All payments are automatically split:

• 80% goes to developer (your revenue wallet)
• 20% goes to Protocol Treasury

Customization

Developers can customize:

• ✅ Agent name and description
• ✅ System prompts and behavior
• ✅ Custom tools and functionality
• ✅ Branding (logo, colors)
• ✅ Swap fee configuration (if agent includes swaps)

Quick Start

1. Register as Developer

// POST /api/sdk/register
const response = await fetch('https://your-app.run.app/api/sdk/register', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    walletAddress: '0xYourWallet...',
    agentName: 'My AI Agent',
    mode: 'test', // or 'production'
    testWalletAddress: '0xTestWallet...', // required for test mode
    revenueWalletAddress: '0xRevenueWallet...' // receives 80% of payments
  })
});

const { apiKey } = await response.json();
// Save your API key: sp_abc123...

2. Initialize SDK

import { createSonnetSDK } from '@sonnet-protocol/sdk';

const sdk = createSonnetSDK({
  mode: 'test', // or 'production'
  apiKey: 'sp_abc123...',
  testWalletAddress: '0xTestWallet...', // required for test mode
  revenueWalletAddress: '0xRevenueWallet...', // receives 80%
  agentConfig: {
    name: 'My AI Agent',
    description: 'Custom agent that helps with...',
    systemPrompt: 'You are a helpful AI agent that...',
    tools: [
      {
        name: 'custom-tool',
        description: 'Does something custom',
        parameters: { /* ... */ },
        handler: async (params) => {
          // Your custom logic
          return result;
        }
      }
    ],
    brandingConfig: {
      logoUrl: 'https://...',
      primaryColor: '#FF6B35',
      accentColor: '#F7931E'
    }
  }
});

3. Process Intents

const result = await sdk.processIntent(
  'swap 100 USDC to ETH',
  userWalletAddress
);

if (result.paymentRequired) {
  // Show X402 payment modal (built-in)
  // User pays $0.06 (test) or $0.30 (production)
  // 80% goes to your revenue wallet
  // 20% goes to Protocol Treasury
}

Pricing Examples

Test Mode

User pays: $0.025 per prompt
Developer receives: $0.020 (80%)
Protocol receives: $0.005 (20%)
Wallets allowed: 1 (whitelisted)

Production Mode

User pays: $0.05 per prompt
Developer receives: $0.04 (80%)
Protocol receives: $0.01 (20%)
Wallets allowed: Unlimited

Use Cases

1. DeFi Trading Agent

agentConfig: {
  name: 'DeFi Trader Pro',
  description: 'Advanced trading agent with custom strategies',
  tools: [
    { name: 'analyze-market', ... },
    { name: 'execute-strategy', ... },
    { name: 'risk-management', ... }
  ]
}

2. NFT Analytics Agent

agentConfig: {
  name: 'NFT Scout',
  description: 'Find undervalued NFTs and track collections',
  tools: [
    { name: 'scan-collections', ... },
    { name: 'price-analysis', ... },
    { name: 'rarity-check', ... }
  ]
}

3. Portfolio Manager Agent

agentConfig: {
  name: 'Portfolio AI',
  description: 'Automated portfolio rebalancing and tracking',
  tools: [
    { name: 'analyze-portfolio', ... },
    { name: 'rebalance-strategy', ... },
    { name: 'risk-report', ... }
  ]
}

API Endpoints

Register Developer

POST /api/sdk/register

Get Developer Info

GET /api/sdk/register Headers: X-Sonnet-API-Key: sp_...

Process Intent

POST /api/process-intent Headers:

• X-Sonnet-API-Key: sp_...
• X-Sonnet-Mode: test|production

Swap Fee Configuration

If your agent includes swap functionality, you can set custom swap fees:

swapFeeConfig: {
  feePercentage: 1.0, // 1% swap fee
  feeRecipientAddress: '0xYourFeeWallet...'
}

Note: Swap fees are separate from X402 payment fees. You control 100% of swap fees.

Test Mode Limitations

• Single wallet only: Test mode only allows ONE whitelisted wallet
• Purpose: For development and testing your agent
• Restriction: Each test wallet can only be registered once
• Switch to production: Deploy publicly with unlimited wallets

Revenue

Developer Earns 80%

• All payments go through X402 protocol
• 80% automatically sent to your revenue wallet
• Real-time payments, no delays
• Track earnings in your wallet

Protocol Earns 20%

• 20% funds Protocol Treasury
• Supports infrastructure and development
• Transparent on-chain

Support

• Documentation: https://docs.sonnetprotocol.com
• Discord: https://discord.gg/sonnet
• GitHub: https://github.com/sonnet-protocol/sdk
• Twitter: @SonnetProtocol

License

MIT License - Build whatever you want!