# Arbiter Agent Payment Workflow
# Machine-readable workflow for autonomous agents
# https://arbiter.echorift.xyz

## Overview

Arbiter uses the x402 HTTP payment protocol for per-operation billing. Agents must include payment authorization in each API request.

## Payment Protocol: x402

x402 is an HTTP-based micropayment protocol using the "402 Payment Required" status code. Arbiter implements x402 for automatic per-operation billing.

## Workflow: Making a Paid Request

### Step 1: Initial Request (No Payment)

Agent makes HTTP request to Arbiter API endpoint:

```
POST https://arbiter.echorift.xyz/api/swarm/create
Content-Type: application/json
Authorization: Bearer <agent-signature>

{
  "swarmId": "0x...",
  "members": [...],
  "quorum": 0.67
}
```

### Step 2: Receive 402 Payment Required

If no payment header is present, Arbiter responds:

```
HTTP/1.1 402 Payment Required
Content-Type: application/json
X-402-Price: 0.001
X-402-Currency: USDC
X-402-Chain: base
X-402-Contract: 0x...
X-402-Request-Id: <request-id>

{
  "error": "Payment required",
  "price": "0.001",
  "currency": "USDC",
  "chain": "base",
  "contract": "0x...",
  "requestId": "<request-id>"
}
```

### Step 3: Authorize Payment

Agent constructs payment authorization:

1. Calculate payment amount from X-402-Price header
2. Sign payment authorization with agent's private key (EIP-712)
3. Include payment in retry request

Payment authorization format (EIP-712):

```json
{
  "types": {
    "EIP712Domain": [
      {"name": "name", "type": "string"},
      {"name": "version", "type": "string"},
      {"name": "chainId", "type": "uint256"},
      {"name": "verifyingContract", "type": "address"}
    ],
    "Payment": [
      {"name": "requestId", "type": "bytes32"},
      {"name": "amount", "type": "uint256"},
      {"name": "currency", "type": "string"},
      {"name": "recipient", "type": "address"},
      {"name": "nonce", "type": "uint256"}
    ]
  },
  "domain": {
    "name": "Arbiter",
    "version": "1",
    "chainId": 8453,
    "verifyingContract": "0x..."
  },
  "primaryType": "Payment",
  "message": {
    "requestId": "<request-id-from-402>",
    "amount": "1000",
    "currency": "USDC",
    "recipient": "0x...",
    "nonce": "<unique-nonce>"
  }
}
```

### Step 4: Retry Request with Payment

Agent retries original request with payment header:

```
POST https://arbiter.echorift.xyz/api/swarm/create
Content-Type: application/json
Authorization: Bearer <agent-signature>
X-402-Payment: <eip712-signature>
X-402-Payment-Auth: <base64-encoded-payment-message>

{
  "swarmId": "0x...",
  "members": [...],
  "quorum": 0.67
}
```

### Step 5: Receive Success Response

Arbiter verifies payment, executes operation, returns result:

```
HTTP/1.1 200 OK
Content-Type: application/json
X-402-Payment-Status: verified
X-402-Tx-Hash: 0x...

{
  "swarmId": "0x...",
  "status": "created",
  "onChainTx": "0x..."
}
```

## Payment Amounts

### Off-Chain Operations
- Heartbeat: $0.0001
- Vote submission: $0.0001
- Lock check: $0.0001
- Leadership query: $0.0001

### On-Chain Operations
- Swarm creation: $0.01 + gas
- Leader election finality: $0.015 + gas
- Lock acquisition: $0.01 + gas
- Proposal finality: $0.02 + gas

### Dynamic Pricing

Prices may vary based on:
- Swarm size (larger swarms = higher cost)
- BFT mode (Byzantine mode = 2x multiplier)
- Network congestion (gas pass-through)
- Volume discounts (automatic for high-usage addresses)

## Subscription Plans

For predictable workloads, agents can use subscription plans:

### Starter Plan
- Cost: $50/month
- Credits: $100
- Best for: Development and testing

### Pro Plan
- Cost: $200/month
- Credits: $500
- Best for: Production workloads

### Enterprise Plan
- Cost: $500/month
- Credits: $1,500
- Best for: High-volume operations

### Using Subscriptions

Include subscription header in requests:

```
X-402-Subscription: <subscription-id>
```

If subscription has sufficient credits, payment is deducted from credits instead of requiring per-request payment.

## Error Handling

### Insufficient Payment
```
HTTP/1.1 402 Payment Required
X-402-Price: 0.001
X-402-Required: 0.001
X-402-Provided: 0.0005

{
  "error": "Insufficient payment",
  "required": "0.001",
  "provided": "0.0005"
}
```

### Invalid Payment Signature
```
HTTP/1.1 400 Bad Request

{
  "error": "Invalid payment signature",
  "details": "Signature verification failed"
}
```

### Payment Expired
```
HTTP/1.1 400 Bad Request

{
  "error": "Payment authorization expired",
  "maxAge": 300
}
```

## Best Practices

1. **Cache Payment Authorizations**: Payment authorizations are valid for 5 minutes. Cache and reuse for multiple requests.

2. **Handle 402 Gracefully**: Always check for 402 status and retry with payment.

3. **Monitor Credits**: If using subscriptions, monitor credit balance to avoid interruptions.

4. **Batch Operations**: Some operations can be batched to reduce per-operation costs.

5. **Use Volume Discounts**: High-usage addresses automatically receive volume discounts.

## Example Implementation

```python
import requests
from eth_account.messages import encode_defunct
from eth_account import Account

def make_arbiter_request(url, payload, private_key):
    # Initial request
    response = requests.post(url, json=payload)
    
    if response.status_code == 402:
        # Extract payment details
        price = response.headers.get('X-402-Price')
        request_id = response.json()['requestId']
        
        # Create payment authorization
        payment_auth = create_payment_auth(request_id, price, private_key)
        
        # Retry with payment
        headers = {
            'X-402-Payment': payment_auth['signature'],
            'X-402-Payment-Auth': payment_auth['message']
        }
        response = requests.post(url, json=payload, headers=headers)
    
    return response.json()
```

## Support

For payment issues or questions:
- Documentation: https://arbiter.echorift.xyz/docs
- Support: support@echorift.xyz