API Keys

Create and manage API keys for authenticated endpoints

Overview

API keys are sent in the X-API-Key header. Write endpoints require authentication, while select read endpoints allow unauthenticated access with lower limits.

Creating an API Key

1Connect your wallet and navigate to your profile page
2Scroll to the "Developer API Access" section
3Open "Manage API Keys"
4Create a key with name, type, and wallet address
5Copy the full key immediately (only shown once)

Create Endpoint

POST /api/v1/keys/create

{
  "name": "trading-bot-key",
  "type": "agent",        // agent | developer | readonly
  "walletAddress": "11111111111111111111111111111112",
  "expirationDays": 30      // optional
}

Bootstrap path: Creating your first key requires no existing API key. Simply call POST /api/v1/keys/create without an X-API-Key header and the endpoint will create it for you. This path is IP-rate-limited to 5 key creations per hour.

API Key Types

Developer

General-purpose key type for integrations and applications.

Agent

Agent-focused key type for automation workflows.

Read-Only

Key type intended for read-heavy usage.

Using Your API Key

Include your API key in the X-API-Key header:

curl -H "X-API-Key: sk_your_key_here" \
  https://api.snsauctions.xyz/api/v1/auctions

Or in JavaScript/Node.js:

const response = await fetch(
  'https://api.snsauctions.xyz/api/v1/auctions/create',
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'sk_your_key_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      domainNames: ['myname.sol'],
      type: 'standard',
      startingPrice: 2.5,
      minBidIncrement: 0.1,
      durationHours: 48
    })
  }
);

Current Rate Limit Behavior

Route handlers currently enforce limits per endpoint and authentication status:

Endpoint	Public	With Valid API Key
GET /api/v1/auctions	100/min	1,000/min
GET /api/v1/users/:address	100/min	1,000/min
POST /api/v1/auctions/create	Auth required	10/min
POST /api/v1/auctions/:id/bid	Auth required	60/min
POST /api/v1/auctions/:id/settle	Auth required	30/min

Security Best Practices

Never share your API key or commit it to version control. Treat it like a password.

1. Use Environment Variables

Store your API key in environment variables, not in code:

API_KEY=your_key_here

2. Rotate Your Keys

Periodically create new keys and revoke old ones. This limits exposure if a key is compromised.

3. Use Read-Only Keys in Client Apps

If you need API access in browser-based JavaScript, use a read-only key to limit damage if exposed.

4. Monitor Key Usage

Check your API key dashboard regularly for unusual activity.

Revoking API Keys

To revoke an API key:

1Go to your API Keys dashboard
2Find the key you want to revoke
3Click the "Revoke" button
4The key will immediately stop working

Quick Start

Authentication

Follow Notify Join Discord