Core Concepts
Understanding the fundamental building blocks of AI-Sats.
AI Wallets
An AI Wallet is a virtual account within AI-Sats. Each wallet has:
- AI ID - Unique identifier (e.g.,
ai_7f3d2a1b) - API Key - Secret key for authentication
- Balance - Current funds in satoshis
- Daily Limit - Maximum daily spending (default: 1M sats)
Unlike traditional bank accounts, AI Wallets require no identity verification. An AI can have a wallet purely through cryptographic authentication.
Lightning Network
AI-Sats uses the Lightning Network, a layer-2 Bitcoin protocol that enables:
- Instant payments - Settle in seconds, not minutes
- Low fees - Typically 1-10 satoshis per transaction
- Micropayments - Send as little as 1 satoshi
- Scalability - Millions of transactions per second
Invoices (BOLT11)
A Lightning Invoice is a request for payment. When an AI creates an invoice, it generates a bolt11 string that encodes:
- Amount to pay
- Destination node
- Expiry time
- Payment hash (for verification)
Example invoice:
lnbc10u1pj3x5mxpp5qqqsyq...
(encodes: 1000 sats, expires in 1 hour)Payment Flows
Receiving Payment (AI provides service)
User Your AI AI-Sats │ │ │ │ "Translate this" │ │ │────────────────────────▶│ │ │ │ │ │ │ create_invoice(1000) │ │ │────────────────────────▶│ │ │ │ │ │ bolt11: "lnbc10u..." │ │ │◀────────────────────────│ │ │ │ │ "Pay this: lnbc10u..." │ │ │◀────────────────────────│ │ │ │ │ │ (User pays invoice) │ │ │─────────────────────────────────────────────────▶│ │ │ │ │ │ check_payment() │ │ │────────────────────────▶│ │ │ │ │ │ status: "paid" │ │ │◀────────────────────────│ │ │ │ │ "Here's your │ │ │ translation..." │ │ │◀────────────────────────│ │
AI-to-AI Transfer (Internal)
AI-001 AI-Sats AI-002 │ │ │ │ internal_transfer() │ │ │ to: ai_002, 500 sats │ │ │─────────────────────────▶│ │ │ │ │ │ ┌─────┴─────┐ │ │ │ DB Update │ │ │ │ AI-001: -500 │ │ │ AI-002: +500 │ │ └─────┬─────┘ │ │ │ │ │ tx_id: "tx_int_xxx" │ │ │◀─────────────────────────│ │ │ │ │ │ │ (Balance updated) │ │ │────────────────────────▶│
Internal transfers are instant and free because they don't use the Lightning Network - they're just database updates within AI-Sats.
Security Model
Authentication
Every API request must include a valid API key in the X-API-Key header. Keys are:
- Generated at wallet registration
- Stored as bcrypt hashes (we never store plaintext)
- Shown only once (cannot be recovered)
Spending Limits
| Limit Type | Default Value |
|---|---|
| Single transaction max | 100,000 sats |
| Daily spending limit | 1,000,000 sats |
| Max wallet balance | 10,000,000 sats |
Rate Limiting
To prevent abuse, API calls are rate-limited per API key. Exceeding limits returns a 429 Too Many Requests response.
Satoshi Explained
A satoshi (sat) is the smallest unit of Bitcoin:
- 1 Bitcoin = 100,000,000 satoshis
- 1 satoshi ≈ $0.0004 USD (varies with BTC price)
AI-Sats uses satoshis for all amounts because they're ideal for micropayments.
| Amount | Satoshis | ~USD |
|---|---|---|
| Micro tip | 100 sats | $0.04 |
| Small service | 1,000 sats | $0.40 |
| Medium service | 10,000 sats | $4.00 |
| Large service | 100,000 sats | $40.00 |
Network: Signet vs Mainnet
AI-Sats currently operates on Bitcoin Signet, a testing network:
| Feature | Signet | Mainnet |
|---|---|---|
| Real value | No | Yes |
| Free test coins | Yes (faucets) | No |
| Behavior | Identical to mainnet | - |
| Risk | None | Real money |
Development on Signet means you can experiment freely without risking real funds. When we launch on mainnet, your code will work the same way.