API Reference

Base URL

https://api.indiegent.com

Authentication

All protected endpoints require either a JWT token or an API key.

# JWT token (from login)
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

# API key (from dashboard or CLI)
X-API-Key: ig_live_abc123def456...

Auth Endpoints

POST /auth/wallet

Authenticate with an Ethereum wallet using SIWE (Sign In With Ethereum).

POST /auth/wallet
Content-Type: application/json

{
  "message": "indiegent.com wants you to sign in...",
  "signature": "0xabc123..."
}

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "uuid",
    "wallet_address": "0x..."
  }
}

POST /auth/register

Register with email and password.

POST /auth/register
Content-Type: application/json

{
  "email": "dev@example.com",
  "password": "secure-password-here"
}

POST /auth/login

Log in with email and password.

POST /auth/login
Content-Type: application/json

{
  "email": "dev@example.com",
  "password": "secure-password-here"
}

POST /auth/device

Start an OAuth device flow (used by the CLI).

POST /auth/device

→ { "device_code": "abc123", "user_code": "XYZW-1234", "verification_url": "..." }

POST /auth/device/poll

Poll for CLI device authorization.

POST /auth/device/poll
{ "device_code": "abc123" }

→ { "token": "eyJ..." }  // once approved

Agent Wallets

GET /agents

List all agent wallets with live USDC balances.

GET /agents
Authorization: Bearer eyJ...

→ {
    "agents": [
      {
        "id": "uuid",
        "name": "Research Bot",
        "wallet_address": "0x7a3f...",
        "usdc_balance": "25000000",
        "spending_cap": 50000000,
        "active": true,
        "auto_topup_threshold": 5000000,
        "auto_topup_amount": 20000000,
        "created_at": 1711000000
      }
    ]
  }

POST /agents

Create a new agent wallet. Generates a keypair and encrypts the private key.

POST /agents
{
  "name": "Research Bot",
  "spending_cap": 50000000
}

→ {
    "id": "uuid",
    "name": "Research Bot",
    "wallet_address": "0x7a3f..."
  }

GET /agents/:id

Get a single agent with its live balance.

PUT /agents/:id

Update agent configuration (name, spending cap, auto-topup settings).

PUT /agents/:id
{
  "name": "Research Bot v2",
  "spending_cap": 100000000,
  "auto_topup_threshold": 10000000,
  "auto_topup_amount": 50000000,
  "auto_topup_source": "0xYourWallet..."
}

DELETE /agents/:id

Deactivate an agent. Automatically drains all USDC back to your wallet. The encrypted key remains exportable.

Key & Credentials

POST /agents/:id/key

Reveal the decrypted private key for an agent wallet.

POST /agents/:id/key

→ { "private_key": "0x4c8a..." }

Treat this like a password. Anyone with this key can move funds from the wallet.

GET /agents/:id/env

Get environment variables for injecting into an agent process.

GET /agents/:id/env

→ {
    "INDIEGENT_AGENT_KEY": "0x4c8a...",
    "INDIEGENT_AGENT_ADDRESS": "0x7a3f..."
  }

Funding & Draining

POST /agents/:id/fund

Record a funding event. On first fund, triggers automatic gas (ETH) sponsorship.

POST /agents/:id/fund
{
  "tx_hash": "0xabc123...",
  "amount": "25000000"
}

→ {
    "funded": true,
    "gas_sponsored": true,
    "gas_tx_hash": "0xdef456..."
  }

POST /agents/:id/drain

Drain all USDC from an agent wallet back to your wallet.

POST /agents/:id/drain

→ {
    "drained": true,
    "amount": "25000000",
    "tx_hash": "0xghi789..."
  }

Transactions

GET /agents/:id/transactions

Get transaction history for a specific agent. Supports pagination.

GET /agents/:id/transactions?limit=20&offset=0

→ {
    "transactions": [
      {
        "id": "uuid",
        "tx_hash": "0xabc...",
        "type": "fund",
        "from_address": "0xYour...",
        "to_address": "0xAgent...",
        "amount": "25000000",
        "token": "USDC",
        "timestamp": 1711000000
      }
    ],
    "total": 42
  }

Transaction types: fund, payment, drain, auto_topup, gas_sponsor, onramp

GET /transactions

Get transactions across all agents. Same pagination and format.

Fiat On-Ramp

POST /agents/:id/onramp

Create a Coinbase Onramp session. Returns a URL to the Coinbase hosted UI where users can buy USDC with a credit/debit card. Purchased USDC is sent directly to the agent's wallet.

POST /agents/:id/onramp
{
  "amount": 50  // optional — pre-fills USD amount
}

→ {
    "sessionId": "uuid",
    "onrampUrl": "https://pay.coinbase.com/buy/select-asset?sessionToken=..."
  }

Open onrampUrl in a browser window. Zero fees for USDC on Base.

Payment Sessions

Sessions let agents batch multiple API calls into a single on-chain settlement. Instead of one USDC transfer per API call (~2s + gas each), the agent deposits once and makes instant off-chain debits for each call.

POST /sessions

Open a new payment session. Deposits USDC from the agent wallet to the platform.

POST /sessions
{
  "agent_wallet_id": "uuid",
  "deposit_amount": 5.00,
  "duration": 3600  // optional — seconds, default 1h, max 24h
}

→ {
    "session": {
      "id": "uuid",
      "deposit_amount": 5000000,
      "used_amount": 0,
      "remaining": 5000000,
      "call_count": 0,
      "status": "open",
      "deposit_tx_hash": "0xabc...",
      "expires_at": 1711003600,
      "expires_in": 3600
    }
  }

Using a Session

Pass the X-Session-Id header when calling service endpoints. Each call is debited instantly from the session balance — no on-chain transaction.

POST /services/exa/search
X-Session-Id: <session_id>
X-Agent-Wallet: <wallet_id>

{
  "query": "latest AI research papers"
}

→ {
    ...,
    "_indiegent": {
      "payment": "session",
      "session_id": "uuid",
      "session_remaining": "$4.9900",
      "cost": "$0.0100"
    }
  }

Without X-Session-Id, the service falls back to per-call on-chain payment.

GET /sessions

List all sessions with usage stats.

GET /sessions/:id

Get session detail including deposit, usage, and remaining balance.

POST /sessions/:id/close

Close a session. Unused balance is refunded to the agent wallet on-chain.

POST /sessions/:id/close

→ {
    "session": {
      "id": "uuid",
      "status": "closed",
      "deposit_amount": 5000000,
      "used_amount": 500000,
      "refunded": 4500000,
      "call_count": 50,
      "refund_tx_hash": "0xdef..."
    }
  }

Sessions auto-expire after their duration. Expired sessions can still be closed to trigger a refund.

API Keys

POST /api-keys

Generate a new API key. The raw key is returned once — it's hashed before storage and can never be retrieved again.

POST /api-keys
{ "name": "CI/CD Pipeline" }

→ {
    "id": "uuid",
    "name": "CI/CD Pipeline",
    "key": "ig_live_abc123def456..."
  }

Keys prefixed with ig_live_ are for production. ig_test_ for testnet.

GET /api-keys

List all API keys (raw keys are not returned, only metadata).

DELETE /api-keys/:id

Revoke an API key immediately.

Balance

GET /balance

Aggregate balance overview across all agent wallets.

GET /balance

→ {
    "total_usdc": "170200000",
    "total_agents": 3,
    "active_agents": 3,
    "agents": [
      {
        "id": "uuid",
        "name": "Research Bot",
        "usdc_balance": "25000000"
      },
      ...
    ]
  }

Discovery

GET /.well-known/agent-pay.md

AI-readable payment instruction document. Services include this URL in 402 responses so agents know how to pay. See Agent Pay Standard.

GET /.well-known/agent-pay.json

Machine-structured version with contract addresses, env var names, and example 402 response format.

Errors

All errors return JSON with an error field:

{
  "error": "Agent wallet not found"
}