Authentication

The Suwappu Agent API uses Bearer token authentication. Every authenticated request must include your API key in the Authorization header.

Bearer Token Format

Authorization: Bearer suwappu_sk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

API keys follow this format:

• Prefix: suwappu_sk_
• Body: Alphanumeric characters, hyphens, and underscores ([a-zA-Z0-9_-]+)
• Minimum length: 32 characters total (including the prefix)

Getting an API Key

Call the registration endpoint to create an agent and receive your key. This endpoint is public and does not require authentication.

-kw">curl -X POST https://api.suwappu.bot/v1/agent/register \
  -H -str">"Content-Type: application/json" \
  -d -str">'{-str">"name":-str">"my-agent",-str">"description":-str">"My trading agent"}'

Response:

{
  "hl-key">"success": true,
  "hl-key">"agent": {
    "hl-key">"id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "hl-key">"name": "my-agent",
    "hl-key">"api_key": "suwappu_sk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
    "hl-key">"created_at": "2025-01-15T10:30:00Z"
  }
}

Store your API key securely. It is shown only once at registration time.

Using Your Key

Include the key in the Authorization header on every authenticated request:

-kw">curl -X POST https://api.suwappu.bot/v1/agent/quote \
  -H -str">"Content-Type: application/json" \
  -H -str">"Authorization: Bearer suwappu_sk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -d -str">'{-str">"from_token":-str">"USDC",-str">"to_token":-str">"ETH",-str">"amount":-str">"100.00",-str">"chain":-str">"ethereum"}'

If the key is missing, malformed, or revoked, the API returns a 401 Unauthorized response:

{
  "hl-key">"success": false,
  "hl-key">"error": {
    "hl-key">"code": "UNAUTHORIZED",
    "hl-key">"message": "Invalid or missing API key"
  }
}

Key Rotation

Rotate your API key without re-registering. The old key is immediately invalidated and a new one is returned.

-kw">curl -X POST https://api.suwappu.bot/v1/agent/keys/rotate \
  -H -str">"Authorization: Bearer suwappu_sk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

Response:

{
  "hl-key">"success": true,
  "hl-key">"api_key": "suwappu_sk_x9y8z7w6v5u4t3s2r1q0p9o8n7m6l5k4",
  "hl-key">"rotated_at": "2025-01-20T14:00:00Z"
}

Update your application to use the new key immediately after rotation. The previous key will no longer work.

Public Endpoints

The following endpoints do not require authentication:

Method	Endpoint	Description
POST	/register	Create a new agent and receive an API key
GET	/chains	List supported blockchain networks
GET	/openapi	OpenAPI specification for the API

All other endpoints require a valid Bearer token.

Security Best Practices

• Never expose your API key in client-side code, public repositories, or logs.
• Use environment variables or a secrets manager to store keys.
• Rotate keys periodically and immediately if you suspect a compromise.
• Each agent should have its own dedicated key.

Next Steps

• Review Rate Limits to understand request quotas for each tier.
• See Quick Start for a full walkthrough of the swap flow.