Documentation

{
  "mandate_id": "mandate_abc123",
  "agent_id": "agent_shopping_assistant",
  "user_id": "user_12345",
  
  "items": [
    {
      "product_id": "prod_001",
      "name": "Ergonomic Office Chair",
      "quantity": 1,
      "unit_price": 299.99
    }
  ],
  "total_amount": 299.99,
  "currency": "USD",
  
  "shipping": {
    "name": "John Doe",
    "street": "123 Main St",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94102",
    "country": "US"
  },
  
  "merchant_id": "merchant_xyz",
  "callback_url": "https://agent.example.com/order-status",
  "simulation": false
}

import hmac
import hashlib
import json

def sign_ap2_mandate(mandate: dict, secret: str) -> str:
    """Generate AP2 signature for a mandate."""
    mandate_json = json.dumps(mandate, separators=(',', ':'), sort_keys=True)
    signature = hmac.new(
        secret.encode(),
        mandate_json.encode(),
        hashlib.sha256
    ).hexdigest()
    return signature

# Usage
mandate = {...}  # Your mandate object
signature = sign_ap2_mandate(mandate, "your_shared_secret")

# Include in request headers
headers = {
    "X-Agent-Signature": signature,
    "Content-Type": "application/json"
}

// POST /api/alerts/create
const alert = await fetch('https://engine.pennylane.dev/api/alerts/create', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    product_id: 'sku_123',
    merchant_id: 'target_store',
    alert_type: 'price_drop',       // or 'back_in_stock', 'deal_percentage'
    target_price: 99.99,            // Alert when price <= this
    notification_channel: 'webhook',
    webhook_url: 'https://my-agent.com/alerts',
    agent_id: 'my_shopping_bot',
    notify_once: true
  })
});

// Response: { id: "alert_xyz", status: "active", message: "..." }

{
  "alert_id": "alert_xyz789",
  "alert_type": "price_drop",
  "triggered_at": "2026-01-22T15:30:00Z",
  "product_id": "sku_123",
  "product_name": "Wireless Headphones",
  "initial_price": 149.99,
  "current_price": 89.99,
  "discount_percentage": 40,
  "buy_url": "https://store.com/checkout/sku_123"
}

// POST /api/well/register
const response = await fetch('https://engine.pennylane.dev/api/well/register', {
  method: 'POST',
  headers: { 'X-API-Key': 'pk_live_your_key' }
});

// Response:
// {
//   "success": true,
//   "agent_id": "abc123def456",
//   "status": "registered",
//   "message": "Agent registered as in-network. No fees on matches."
// }

// GET /api/well/fees
const fees = await fetch('https://engine.pennylane.dev/api/well/fees', {
  headers: { 'X-API-Key': 'pk_live_your_key' }
});

// Response:
// {
//   "total_fees": 2.50,
//   "pending_fees": 1.25,
//   "fee_count": 5,
//   "message": "Subscribe to avoid fees: pennylane.dev/pricing"
// }