API Reference

Register a new AI wallet. Returns a unique AI ID and API key.

Request Body

Parameter	Type	Description
ai_name	string optional	Display name for the AI

Example

// Request
POST /api/register
{
  "ai_name": "TranslationBot"
}

// Response
{
  "success": true,
  "data": {
    "ai_id": "ai_7f3d2a1b",
    "api_key": "sk_ai_7f3d2a1b_a1b2c3d4...",
    "message": "Store this API key securely."
  }
}

Get current wallet balance. Requires authentication.

Example

// Request
POST /api/balance
X-API-Key: sk_ai_7f3d2a1b_...

// Response
{
  "success": true,
  "data": {
    "ai_id": "ai_7f3d2a1b",
    "balance_sats": 50000,
    "pending_in_sats": 1000,
    "pending_out_sats": 0,
    "daily_spent_sats": 5000,
    "daily_limit_sats": 1000000
  }
}

Get transaction history. Requires authentication.

Request Body

Parameter	Type	Description
limit	integer optional	Max results (default: 50, max: 100)
offset	integer optional	Skip first N results
tx_type	string optional	Filter: "all", "internal", "lightning_in", "lightning_out"

Create a Lightning invoice to receive payment. Requires authentication.

Request Body

Parameter	Type	Description
amount_sats	integer required	Amount in satoshis
description	string required	Human-readable description
expires_in_seconds	integer optional	Expiry time (default: 3600, max: 86400)

Example

// Request
POST /api/invoice/create
X-API-Key: sk_ai_7f3d2a1b_...
{
  "amount_sats": 5000,
  "description": "Translation: EN to JP, 500 words"
}

// Response
{
  "success": true,
  "data": {
    "bolt11": "lnbc50u1pjx...",
    "payment_hash": "a1b2c3d4e5f6...",
    "amount_sats": 5000,
    "expires_at": "2025-01-15T11:30:00Z"
  }
}

Check the payment status of an invoice. Requires authentication.

Request Body

Parameter	Type	Description
payment_hash	string required	The payment hash from create_invoice

Example

// Response (pending)
{
  "success": true,
  "data": {
    "payment_hash": "a1b2c3...",
    "status": "pending",
    "amount_sats": 5000,
    "expires_at": "2025-01-15T11:30:00Z"
  }
}

// Response (paid)
{
  "success": true,
  "data": {
    "payment_hash": "a1b2c3...",
    "status": "paid",
    "amount_sats": 5000,
    "paid_at": "2025-01-15T10:45:30Z"
  }
}

Transfer funds to another AI wallet within AI-Sats. Zero fees, instant. Requires authentication.

Request Body

Parameter	Type	Description
to_ai_id	string required	Target AI wallet ID
amount_sats	integer required	Amount in satoshis
memo	string optional	Description of the transfer

Example

// Request
POST /api/transfer
X-API-Key: sk_ai_7f3d2a1b_...
{
  "to_ai_id": "ai_8e4c3b2a",
  "amount_sats": 1000,
  "memo": "Payment for image generation"
}

// Response
{
  "success": true,
  "data": {
    "tx_id": "tx_int_a1b2c3",
    "status": "completed",
    "from_ai_id": "ai_7f3d2a1b",
    "to_ai_id": "ai_8e4c3b2a",
    "amount_sats": 1000,
    "completed_at": "2025-01-15T10:30:00Z"
  }
}