eIOU API Overview

What You'll Learn

• Understanding the eIOU API architecture
• Available endpoints and resources
• Authentication methods
• Request and response formats
• Rate limiting and best practices

API Architecture

The eIOU API follows RESTful principles and provides JSON-formatted responses. All API access is performed over HTTPS with authentication via API keys.

Base URL

https://api.eiou.org/v1

Note - This URL is planned and not yet active

Core Resources

Contacts Management

Manage your network of trusted contacts:

• GET /contacts - List all contacts
• POST /contacts - Add new contact
• GET /contacts/:id - Get contact details
• PUT /contacts/:id - Update contact
• DELETE /contacts/:id - Remove contact

Transactions

Send and receive eIOUs:

• POST /transactions - Send eIOU
• GET /transactions - List transaction history
• GET /transactions/:id - Get transaction details
• GET /balances - View current balances

Peer-to-Peer Operations

Handle indirect transactions through the network:

• POST /p2p/request - Initiate P2P transaction
• GET /p2p/requests - List P2P requests
• POST /p2p/respond - Respond to P2P request
• GET /p2p/responses - View P2P responses

Configuration

Manage wallet and settings:

• GET /wallet/info - Get wallet information
• GET /settings - View current settings
• PUT /settings - Update settings

Message Relay Service

The eIOU API at api.eiou.org functions as a decentralized message relay service. This enables secure communication between eIOU nodes without requiring direct connections.

How the Relay Works

• Encryption: All messages are encrypted using the recipient's public key before transmission
• Relay Function: api.eiou.org acts as a neutral relay point, forwarding encrypted messages without access to their contents
• Universal Delivery: Encrypted messages can be received at any functioning eIOU endpoint URL
• Privacy Preserved: The relay cannot decrypt messages - only the intended recipient with the private key can

Relay Endpoints

• POST /relay/send - Send an encrypted message through the relay
• GET /relay/messages - Check for pending messages at your endpoint
• GET /relay/status/:messageId - Check delivery status of a relayed message
• POST /relay/register - Register your eIOU endpoint URL with the relay

Example Relay Usage

Sending an encrypted message through the relay:

curl -X POST https://api.eiou.org/v1/relay/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_public_key": "recipient_pubkey_here",
    "encrypted_payload": "base64_encrypted_data",
    "recipient_endpoint": "https://recipient.eiou-node.com"
  }'

Benefits of the Relay Architecture

• Decentralization: No single point of failure - messages can be routed through multiple relays
• NAT Traversal: Enables communication between nodes behind firewalls or NAT
• Async Communication: Recipients don't need to be online when messages are sent
• Privacy: End-to-end encryption ensures only intended recipients can read messages
• Scalability: Multiple relay nodes can be deployed to handle increased traffic

Authentication

All API requests require authentication using an API key passed in the request header:

Authorization: Bearer YOUR_API_KEY

Example Request

Here's an example of sending an eIOU via the API:

curl -X POST https://api.eiou.org/v1/transactions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "Bob",
    "amount": 100,
    "currency": "USD"
  }'

Note - This is a conceptual example for the planned API

Response Format

All API responses follow a consistent JSON structure:

{
  "success": true,
  "data": {
    "transaction_id": "txn_abc123",
    "recipient": "Bob",
    "amount": 100,
    "currency": "USD",
    "status": "completed"
  },
  "timestamp": "2025-07-01T12:00:00Z"
}

Error Handling

The API uses standard HTTP status codes and provides detailed error messages:

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_CREDIT",
    "message": "Insufficient credit limit with recipient",
    "details": {
      "required": 100,
      "available": 50
    }
  },
  "timestamp": "2025-07-01T12:00:00Z"
}

Rate Limiting

The API will implement rate limiting to ensure fair usage:

• Standard tier: 1000 requests per hour
• Premium tier: 10,000 requests per hour
• Enterprise: Custom limits

Rate limit headers will be included in all responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1625140800

SDKs and Libraries

Official SDKs are planned for popular programming languages:

• JavaScript/TypeScript (Node.js and browser)
• Python
• PHP
• Go
• Ruby
• Java

Webhooks

The API will support webhooks for real-time event notifications:

• Transaction received
• Contact request received
• P2P request initiated
• Balance changes

Next Steps

Explore the detailed documentation for each API resource: