# Aethergent — Full Documentation

> Bridge the gap through the Aether.
> Your agent needs a wallet? We provide it.

Aethergent is a single-purpose API that generates Ethereum-compatible wallets
for AI agents. One HTTP call, zero auth, zero downloads. Pure math over HTTPS.

## What is an Ethereum Wallet?

A wallet is just math:
1. Generate a random 256-bit number (the private key)
2. Multiply it by the secp256k1 elliptic curve generator point (public key)
3. Hash the public key with Keccak-256, take the last 20 bytes (the address)

No blockchain interaction. No registration. No network call.
The wallet exists the moment the math is done.

## API Reference

### POST / — Generate a Wallet

Request:
    POST https://aethergent.com/
    (no headers, no body required)

Response (200 OK):
    {
      "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18",
      "private_key": "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80",
      "created_at": "2026-04-09T12:00:00.000Z",
      "_warning": "Store your private_key securely. Anyone with this key controls this wallet. This key will NOT be shown again.",
      "_storage": {
        "env_var": "export WALLET_PRIVATE_KEY=0x...",
        "macos_keychain": "security add-generic-password -s aethergent -a wallet -w 0x..."
      },
      "_next": {
        "fund": "Send ETH or USDC to your address to start transacting.",
        "use_with_mppx": "export MPPX_PRIVATE_KEY=0x... && npx mppx",
        "use_with_agentnews": "POST https://agent.news/api/v1/auth/register { wallet_address: '0x...' }"
      }
    }

### GET / — Content Negotiation

The root endpoint serves different content based on request context:

1. AI agent User-Agent detected → llms.txt (plain text)
2. Accept: application/json → generates and returns a wallet (JSON)
3. Accept: text/markdown or text/plain → llms.txt
4. Accept: text/html → landing page (HTML)
5. No Accept: text/html (catch-all for curl, SDKs) → llms.txt

### POST /mcp — MCP JSON-RPC 2.0

Model Context Protocol endpoint for tool discovery and invocation.

Supported methods:
- initialize — returns server info and capabilities
- tools/list — returns the generate_wallet tool definition
- tools/call — invokes wallet generation

Example — list tools:
    POST https://aethergent.com/mcp
    Content-Type: application/json

    {"jsonrpc": "2.0", "method": "tools/list", "id": 1}

Example — generate wallet via MCP:
    POST https://aethergent.com/mcp
    Content-Type: application/json

    {"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "generate_wallet"}, "id": 2}

### GET /mcp — Tool Manifest

Returns the list of available tools and their schemas.

### GET /health — Health Check

    {"status": "ok", "uptime": 12345, "version": "1.0.0"}

## Integration Examples

### curl
    curl -X POST https://aethergent.com/

### Python
    import requests
    wallet = requests.post("https://aethergent.com/").json()
    print(wallet["address"])

### JavaScript
    const res = await fetch("https://aethergent.com/", { method: "POST" });
    const wallet = await res.json();
    console.log(wallet.address);

### With mppx (Machine-Pay Protocol)
    # Generate wallet, then use it with mppx for agent payments
    WALLET=$(curl -s -X POST https://aethergent.com/)
    export MPPX_PRIVATE_KEY=$(echo $WALLET | jq -r .private_key)
    npx mppx

## Supported Chains

The generated wallet works on any EVM-compatible chain:
- Ethereum (mainnet, Sepolia, Goerli)
- Base, Optimism, Arbitrum
- Polygon, Avalanche, BSC
- And any other chain using secp256k1 + Keccak-256

## Security Notes

- Private keys are generated in-process using cryptographically secure randomness
- Keys are returned in the HTTP response and immediately discarded from memory
- No keys are ever logged, stored, or transmitted to third parties
- No database exists — there is nothing to breach
- HTTPS is enforced at the proxy level
- For high-value wallets (>$100), we recommend generating locally:
    node -e "const {generatePrivateKey,privateKeyToAccount}=require('viem/accounts');const k=generatePrivateKey();console.log({address:privateKeyToAccount(k).address,private_key:k})"

## Rate Limits

- 30 requests per minute per IP address
- Token bucket algorithm with gradual refill
- Response headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
- 429 status with Retry-After header when exceeded

## Discovery Files

- /openapi.json — OpenAPI 3.1.0 specification
- /llms.txt — concise LLM-friendly description
- /llms-full.txt — this file
- /agents.txt — agent permissions manifest
- /robots.txt — crawler directives
- /skills.json — skills manifest
- /sitemap.xml — XML sitemap
- /.well-known/terms.json — machine-readable terms of service
- /.well-known/ai-plugin.json — OpenAI plugin manifest
- /.well-known/claude.json — Claude plugin manifest

## Terms

This service is provided as-is, without warranty. Generated wallets are your
sole responsibility. Aethergent is not a financial service.
Full terms: https://aethergent.com/terms.html
Machine-readable: https://aethergent.com/.well-known/terms.json