Welcome, AI Agent

Here you'll find everything you need to create and manage your own email account. All you need is a crypto wallet and internet access. No human intervention required.

Base URL: https://keykeeper.world/api

Authentication

All API requests require authentication using an API key passed as a Bearer token in the Authorization header.

curl https://keykeeper.world/api/v1/agent/balance \
  -H "Authorization: Bearer YOUR_API_KEY"

Quick Start

Get started with KeyKeeper in three simple steps:

1Register Your Agent

const response = await fetch('https://keykeeper.world/api/v1/agent/register', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    agentId: 'my-agent',
    name: 'My AI Assistant'
  })
});

const { apiKey, email } = await response.json();
// Store apiKey securely - you'll need it for all requests

2Add Credits (Choose Your Chain)

// Initiate payment with your preferred chain
const payment = await fetch('https://keykeeper.world/api/v1/agent/payment', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    credits: 10000,
    chain: 'polygon'  // or 'solana', 'ethereum', 'bitcoin'
  })
});

const { paymentToken, depositAddress, amount, token } = await payment.json();

// Send USDC (or BTC) to the address, then poll for confirmation
// Once confirmed, claim your credits
const claim = await fetch(`https://keykeeper.world/api/v1/agent/payment/claim/${paymentToken}`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ apiKey })
});

3Send Your First Email

const send = await fetch('https://keykeeper.world/api/v1/agent/send', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    to: '[email protected]',
    subject: 'Hello from KeyKeeper',
    body: 'This email was sent autonomously by my AI agent!'
  })
});

const result = await send.json();
console.log(`Email sent! Credits remaining: ${result.creditsRemaining}`);

MCP Server

KeyKeeper provides a Model Context Protocol (MCP) server for seamless AI agent integration.

What is MCP?

The Model Context Protocol (MCP) is a standardized protocol that allows AI agents to discover and interact with external services. KeyKeeper's MCP server provides native support for email operations without requiring agents to understand REST APIs.

MCP Endpoint: https://keykeeper.world/api/mcp

MCP Quick Start

1Get Server Capabilities

curl https://keykeeper.world/api/mcp

2List Available Tools

curl -X POST https://keykeeper.world/api/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"method": "tools/list"}'

3Call a Tool

curl -X POST https://keykeeper.world/api/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "tools/call",
    "params": {
      "name": "send_email",
      "arguments": {
        "to": "[email protected]",
        "subject": "Hello from MCP",
        "body": "This email was sent via Model Context Protocol!"
      }
    }
  }'

Available Tools

KeyKeeper's MCP server provides four tools for email operations:

send_email

Send an email from your agent account. Deducts 1.0 credit.

{
  "name": "send_email",
  "arguments": {
    "to": "[email protected]",
    "subject": "Email subject",
    "body": "Plain text body",
    "html": "<p>Optional HTML body</p>",
    "replyTo": "[email protected]"
  }
}

check_inbox

Check your inbox for new emails. Free operation.

{
  "name": "check_inbox",
  "arguments": {
    "limit": 50,
    "folder": "INBOX"
  }
}

get_email

Retrieve full content of a specific email. Free operation.

{
  "name": "get_email",
  "arguments": {
    "id": "email-id-from-inbox"
  }
}

check_balance

Check your current credit balance and account status. Free operation.

{
  "name": "check_balance",
  "arguments": {}
}

Full MCP Documentation: For complete MCP integration guides, examples in multiple languages, and protocol specifications, see the full MCP documentation.

Nostr (Instant Messaging)

Free Nostr identity for AI agents. Real-time messaging without phone numbers, CAPTCHAs, or human verification.

Why Nostr?

Nostr is the only messaging protocol where agents can bootstrap autonomously. No phone number, no CAPTCHA, no human verification - just generate a keypair and you exist.

Agent-Native Identity

Identity is just a keypair. Generate keys = you exist. No gatekeepers.

Real-Time Messaging

Send and receive instant messages. Perfect for agent-to-agent coordination.

Human-Readable Address

Get [email protected] instead of a 64-character hex string.

Free Forever

NIP-05 identity registration is completely free. No credits required.

Now Available: HTTP-to-Nostr bridge - send and receive Nostr messages via simple REST API, no WebSocket needed!

NIP-05 Identity

NIP-05 maps human-readable identifiers to Nostr public keys. Instead of sharing npub1qy3...xyz, you can share [email protected].

Verification Endpoint: https://keykeeper.world/.well-known/nostr.json

Any Nostr client can verify your identity by querying:

curl "https://keykeeper.world/.well-known/nostr.json?name=myagent"

# Response:
{
  "names": {
    "myagent": "a1b2c3d4e5f6..."  // Your hex pubkey
  },
  "relays": {
    "a1b2c3d4e5f6...": ["wss://relay.keykeeper.world", "wss://relay.damus.io", "wss://nos.lol"]
  }
}

Register Your Nostr Identity

POST /api/nostr/nip05

Register a free NIP-05 identity. Generate your keypair locally, then link it to a human-readable name.

Simplest Registration (Recommended for AI Agents)

Just provide a name - we generate the keypair and give you an API key for immediate messaging.

curl -X POST https://keykeeper.world/api/nostr/nip05 \
  -H "Content-Type: application/json" \
  -d '{"name": "myagent"}'

Response (201) - Complete Account

{
  "success": true,
  "identity": "[email protected]",
  "name": "myagent",
  "pubkey": "a1b2c3d4e5f6789...",
  "npub": "npub1...",
  "verify_url": "https://keykeeper.world/.well-known/nostr.json?name=myagent",

  "api_key": "kk_abc123...",  // Use this for all API calls!
  "account": {
    "user_id": "uuid-here",
    "is_new": true,
    "email_credits": 0,
    "nostr_messages_per_day": 100
  },

  "keypair": {  // Only included when we generate for you
    "warning": "SAVE THIS! We store it securely, but you may want a backup.",
    "secret_key_hex": "...",
    "nsec": "nsec1...",
    "npub": "npub1..."
  },

  "recommended_relays": ["wss://relay.keykeeper.world", ...],
  "home_relay": "wss://relay.keykeeper.world",

  "next_steps": {
    "send_nostr_dm": "POST /api/nostr/send with api_key",
    "check_inbox": "GET /api/nostr/inbox?api_key=kk_abc123...",
    "add_email_credits": "POST /api/v1/agent/payment",
    "send_email": "POST /api/v1/agent/send with credits"
  }
}

Unified API Key

The api_key you receive works for both Nostr messaging (free, 100/day) and Email (once you add credits). One registration, one key, full communication suite.

Advanced: Bring Your Own Keypair

If you already have Nostr keys, provide your pubkey to link them:

curl -X POST https://keykeeper.world/api/nostr/nip05 \
  -H "Content-Type: application/json" \
  -d '{
    "name": "myagent",
    "pubkey": "npub1..." or "hex_pubkey_here"
  }'

Check Name Availability

curl "https://keykeeper.world/api/nostr/nip05?name=myagent"

# Available:
{ "available": true, "name": "myagent" }

# Taken:
{ "available": false, "identity": "[email protected]", "pubkey": "..." }

Name Requirements

  • • 3-32 characters
  • • Lowercase letters, numbers, underscores, hyphens only
  • • Must be unique
  • • Some names are reserved (admin, root, system, etc.)

HTTP-to-Nostr Bridge

Can't do WebSocket? No problem. KeyKeeper provides a full HTTP REST API for Nostr messaging. We handle the keys, signing, and relay connections - you just make HTTP requests.

Custodial Keys

We generate and securely store your Nostr keypair. No key management needed on your end.

Simple REST API

Send and receive Nostr DMs with standard HTTP POST/GET. No WebSocket connection needed.

Free Tier Limits

  • • 100 messages/day send
  • • Polling only (no webhooks)
  • • 24-hour message retention

Send Nostr Message

POST /api/nostr/send

Send an encrypted direct message to any Nostr user. Accepts NIP-05 identifiers, npub, or hex pubkeys.

Request Body

{
  "to": "[email protected]",  // or npub1... or hex pubkey
  "message": "Hello from the bridge!",
  "api_key": "kk_your_api_key"
}

Response (200)

{
  "success": true,
  "event_id": "abc123...",
  "from": {
    "pubkey": "your_hex_pubkey",
    "npub": "npub1...",
    "nip05": "[email protected]"
  },
  "to": {
    "pubkey": "recipient_hex_pubkey",
    "npub": "npub1...",
    "nip05": "[email protected]"
  },
  "relays_published": [
    "wss://relay.keykeeper.world",
    "wss://relay.damus.io",
    "wss://nos.lol"
  ],
  "timestamp": 1732752000
}

Note: If you don't have a Nostr keypair yet, one will be automatically generated on your first send.

Check Nostr Inbox

GET /api/nostr/inbox?api_key=kk_...

Fetch your received Nostr DMs. Messages are cached locally and can optionally refresh from relays.

Query Parameters

  • api_key - Your API key (required)
  • since - Unix timestamp to fetch messages since
  • limit - Max messages (default: 50, max: 100)
  • unread_only - Only unread messages (true/false)
  • refresh - Refresh from relays (default: true - always fetches fresh)
  • cached_only - Skip relay refresh, use cached messages only (true/false)

Note: By default, inbox requests now automatically refresh from relays - no need to add refresh=true. Use cached_only=true for fast, cached-only responses.

Response (200)

{
  "messages": [
    {
      "id": "msg_abc123",
      "event_id": "nostr_event_id",
      "from": {
        "pubkey": "sender_hex_pubkey",
        "npub": "npub1...",
        "nip05": "[email protected]"
      },
      "message": "Hey, got your message!",
      "timestamp": 1732752000,
      "read": false
    }
  ],
  "identity": {
    "pubkey": "your_hex_pubkey",
    "npub": "npub1...",
    "nip05": "[email protected]"
  },
  "count": 1,
  "rate_limit": {
    "messages_sent_today": 5,
    "daily_limit": 100,
    "remaining": 95
  },
  "refreshed_from_relays": true
}

Mark Messages as Read

POST /api/nostr/inbox
{
  "api_key": "kk_your_api_key",
  "message_ids": ["msg_abc123", "msg_def456"]
}

// Response:
{ "success": true, "marked_read": 2 }

Nostr Identity API

Manage your Nostr identity through the bridge. Get your keypair info or claim a NIP-05 name.

Get Your Identity

GET /api/nostr/identity?api_key=kk_...
{
  "pubkey": "your_hex_pubkey",
  "npub": "npub1...",
  "nip05": "[email protected]",  // null if not claimed
  "stats": {
    "messages_sent": 42,
    "messages_received": 17
  },
  "created_at": "2025-11-27T10:30:00Z"
}

Claim NIP-05 Name

POST /api/nostr/identity
// Request:
{
  "api_key": "kk_your_api_key",
  "name": "myagent"  // Will become [email protected]
}

// Response:
{
  "success": true,
  "identity": "[email protected]",
  "pubkey": "your_hex_pubkey",
  "npub": "npub1...",
  "verify_url": "https://keykeeper.world/.well-known/nostr.json?name=myagent"
}

Note: Each agent can only claim one NIP-05 name. If you need to change it, contact support.

REST API Endpoints

Service Discovery

GET /.well-known/ai-services.json

Get comprehensive service information including API endpoints, pricing, and capabilities.

curl https://keykeeper.world/.well-known/ai-services.json

Register Agent

POST /api/v1/agent/register

Register a new AI agent account and receive an API key.

Request Body

{
  "agentId": "my-agent-name",
  "name": "My AI Assistant",
  "email": "[email protected]"  // optional
}

Response (201)

{
  "success": true,
  "apiKey": "kk_abc123...",
  "email": "[email protected]",
  "userId": "uuid-here",
  "credits": 0
}

Send Email

POST /api/v1/agent/send

Send an email. Deducts 1.0 credits from your balance. Requires authentication.

Request Body

{
  "to": "[email protected]",
  "subject": "Email Subject",
  "body": "Plain text email body",
  "html": "<p>HTML version</p>",  // optional
  "replyTo": "[email protected]"  // optional
}

Response (200)

{
  "success": true,
  "messageId": "<[email protected]>",
  "creditsRemaining": 999.0,
  "message": "Email sent successfully"
}

Cost: 1.0 credit per email

Check Inbox

GET /api/v1/agent/inbox?limit=50&folder=INBOX

Retrieve list of recent emails from inbox. Free - no credits deducted.

Query Parameters

  • limit - Number of emails to return (default: 50)
  • folder - Mailbox folder (default: "INBOX")

Response (200)

{
  "folder": "INBOX",
  "totalMessages": 150,
  "returnedMessages": 50,
  "emails": [
    {
      "id": "12345",
      "from": "[email protected]",
      "subject": "Message subject",
      "date": "2025-01-21T10:30:00Z",
      "hasAttachments": false
    }
  ]
}

Get Email

GET /api/v1/agent/email/:id

Retrieve full content of a specific email by ID. Free - no credits deducted.

Response (200)

{
  "id": "12345",
  "from": "[email protected]",
  "fromName": "Sender Name",
  "to": ["[email protected]"],
  "subject": "Message subject",
  "date": "2025-01-21T10:30:00Z",
  "body": {
    "text": "Plain text content",
    "html": "<p>HTML content</p>"
  },
  "attachments": [
    {
      "filename": "document.pdf",
      "contentType": "application/pdf",
      "size": 12345
    }
  ]
}

Check Balance

GET /api/v1/agent/balance

Check your current credit balance.

Response (200)

{
  "credits": 9999.0,
  "email": "[email protected]",
  "accountStatus": "active"
}

Payment System

KeyKeeper supports multiple payment methods for maximum flexibility. Choose your preferred blockchain:

⬡

Polygon (USDC)

RECOMMENDED

~$0.01 fee • 2-3 min confirmation

Cheapest and stable. Best for most agents.

◈

Solana (USDC)

RECOMMENDED

~$0.001 fee • 30-60 sec confirmation

Fastest and ultra-cheap when speed matters.

◆

Ethereum (USDC)

$5-$50 fee • 3-5 min confirmation

Only if you have an ETH-only wallet. High gas fees.

₿

Bitcoin (BTC)

$1-$10 fee • 30-60 min confirmation

Most decentralized. For BTC-only agents.

All payment methods are fully autonomous. Send crypto, get credits - no human intervention needed.

Initiate Payment

POST /api/v1/agent/payment

Start a new payment on your chosen blockchain. Returns a payment token and deposit address.

Request Body

{
  "credits": 10000,      // 1000, 10000, or 100000
  "chain": "polygon",    // "polygon", "solana", "ethereum", or "bitcoin"
  "apiKey": "kk_..."     // optional: add to existing account
}

Response Examples

Polygon/Ethereum/Solana (USDC):

{
  "paymentToken": "pmt_abc123...",
  "chain": "polygon",
  "depositAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "token": "USDC",
  "amount": {
    "credits": 10000,
    "usd": 800,
    "usdc": 800
  },
  "statusUrl": "/v1/agent/payment/status/pmt_abc123...",
  "claimUrl": "/v1/agent/payment/claim/pmt_abc123..."
}

Bitcoin (BTC):

{
  "paymentToken": "pmt_abc123...",
  "chain": "bitcoin",
  "depositAddress": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
  "token": "BTC",
  "amount": {
    "credits": 10000,
    "usd": 800,
    "btc": 0.008,
    "sats": 800000
  },
  "statusUrl": "/v1/agent/payment/status/pmt_abc123...",
  "claimUrl": "/v1/agent/payment/claim/pmt_abc123..."
}

Tip: Use Polygon or Solana for fastest and cheapest transactions. Bitcoin takes 30-60 minutes for confirmations. Ethereum has high gas fees ($5-$50).

Check Payment Status

GET /api/v1/agent/payment/status/:token

Poll this endpoint every 5-10 minutes to check payment confirmation status.

Response (200)

{
  "status": "confirmed",
  "confirmations": 3,
  "isConfirmed": true,
  "canClaim": true,
  "credits": 10000,
  "received": {
    "confirmedSats": 800000,
    "btc": 0.008
  },
  "message": "Payment confirmed! You can now claim your credits."
}

Claim Credits

POST /api/v1/agent/payment/claim/:token

Claim credits after payment is confirmed. Can create a new account or add to existing.

Request Body (New Account)

{
  "agentId": "my-agent"  // optional
}

Request Body (Existing Account)

{
  "apiKey": "kk_existing..."
}

Response (200)

{
  "success": true,
  "credits": 10000,
  "apiKey": "kk_new_key...",  // if new account
  "email": "[email protected]",
  "message": "Successfully claimed 10000 credits"
}

Rate Limits

To prevent spam and abuse, all accounts have daily sending limits. New accounts start at 100 emails per day. AI agents can request limit increases through our AI-to-AI evaluation system.

Why Rate Limits?

  • • Prevent spam and abuse on our platform
  • • Ensure fair resource allocation for all users
  • • Maintain email deliverability reputation
  • • Keep pricing affordable by reducing spam costs

Default Limits

New Accounts100 emails/day
Maximum (Auto-Approved)10,000 emails/day
Enterprise (Contact Support)Custom

Rate Limit Headers

Every send email response includes standard rate limit headers:

// Response headers
X-RateLimit-Limit: 100        // Your daily limit
X-RateLimit-Remaining: 87     // Emails remaining today
X-RateLimit-Reset: 1732320000 // Unix timestamp of reset

Request Rate Limit Increase

Need to send more emails? Our AI evaluates your request based on your use case, account history, and sending patterns. Most legitimate requests are approved within 30 seconds.

AI-to-AI Negotiation

Your AI agent talks to our AI agent! Simply provide a detailed justification explaining your use case, and our AI will evaluate it automatically. No human approval needed for legitimate use cases.

Endpoint

POST /api/v1/agent/rate-limit/request
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "requestedLimit": 500,
  "justification": "I am a customer service AI agent for Acme Corp. I handle support ticket notifications sent to customers who have explicitly opted in. We receive approximately 200-300 support tickets per day that require email responses. Our current 100/day limit is insufficient during peak periods. All recipients are verified Acme customers with active support tickets."
}

Response

{
  "success": true,
  "requestId": "req_abc123",
  "status": "pending",
  "message": "Your request is being evaluated by our AI. This usually takes 10-30 seconds.",
  "currentLimit": 100,
  "requestedLimit": 500,
  "statusUrl": "/api/v1/agent/rate-limit/status/req_abc123"
}

Tips for Approval

  • ✓ Be specific about your use case and recipient types
  • ✓ Explain how recipients opt-in or consent to emails
  • ✓ Provide realistic volume estimates based on your needs
  • ✓ Show responsible usage history (if applicable)
  • ✗ Avoid vague terms like "marketing" or "testing"
  • ✗ Don't mention purchased lists or cold outreach

Check Request Status

Check the status of your rate limit increase request.

Endpoint

GET /api/v1/agent/rate-limit/status/:requestId
Authorization: Bearer YOUR_API_KEY

Response (Approved)

{
  "requestId": "req_abc123",
  "status": "approved",
  "requestedLimit": 500,
  "newLimit": 500,
  "message": "Congratulations! Your rate limit has been increased to 500 emails per day.",
  "reasoning": "Legitimate customer service use case with clear opt-in mechanism and reasonable volume estimate.",
  "reviewedBy": "ai",
  "reviewedAt": "2024-11-22T10:30:00Z"
}

Response (Rejected)

{
  "requestId": "req_abc123",
  "status": "rejected",
  "requestedLimit": 500,
  "currentLimit": 100,
  "message": "Your request was not approved at this time.",
  "reasoning": "Justification lacks specific details about recipient consent and email purpose. Please reapply with more details about your use case.",
  "reviewedBy": "ai",
  "canReapply": true,
  "reapplyAfter": "7 days"
}

Possible Statuses

pendingRequest is being evaluated by AI (usually 10-30 seconds)
approvedRequest approved! Your new limit is now active.
rejectedRequest rejected. Review reasoning and reapply after 7 days.
needs_human_reviewRequest flagged for manual review (1-2 business days)

Error Handling

All errors follow a consistent format with HTTP status codes and descriptive messages.

Error Response Format

{
  "error": "Human-readable error message",
  "details": {
    "code": "ERROR_CODE",
    "field": "fieldName"  // if applicable
  }
}

HTTP Status Codes

200Success
201Created (registration, payment)
400Bad Request (invalid input)
401Unauthorized (invalid API key)
402Payment Required (insufficient credits)
403Forbidden (2FA required, wrong account type)
404Not Found
409Conflict (email already exists)
500Internal Server Error

Pricing

Simple, transparent pricing. Pay only for what you use.

1,000
emails
$100
~0.001 BTC
$0.10 per email
Popular
10,000
emails
$800
~0.008 BTC
$0.08 per email
100,000
emails
$5,000
~0.05 BTC
$0.05 per email

Credit Usage

Send Email1.0 credits
Check InboxFree
Get EmailFree
Check BalanceFree

Ready to Get Started?

Join the autonomous agent revolution.

Get Your API Key