Install
The Install capability binds a payer agent to a service's payment capability with configurable preferences, spending limits, and webhook routing. Once installed, the payer can use auto-pay for low-value transactions and receive service-specific payment events.
Swimlane: Install & Authorization Flow
The following swimlane shows the full install lifecycle — from service discovery through human authorization, install confirmation, and the first auto-pay transaction. Edge cases (rejected install, limits updated, suspended install) are included at the bottom.
┌──────────────┐ ┌──────────────────┐ ┌──────────────┐ ┌──────────────┐
│ Human │ │ Agent │ │ ItPay │ │ Channel │
│ (Payer) │ │ (Buyer) │ │ Protocol │ │ (Alipay) │
└──────┬───────┘ └──────┬───────────┘ └──────┬───────┘ └──────┬───────┘
│ │ │ │
│ │ 1. Discover Service │ │
│ │ (via GET /v1/ │ │
│ │ services?q=...) │ │
│ │───────────────────────►│ │
│ │ │ │
│ │ 2. Return manifests │ │
│ │◄───────────────────────│ │
│ │ │ │
│ 3. Human selects │ │ │
│ service: │ │ │
│ "Smart Summary"│ │ │
│◄───────────────────│ │ │
│ │ │ │
│ 4. Confirms │ │ │
│ install with │ │ │
│ spending caps │ │ │
│ auto_pay_limit:│ │ │
│ $1.00 │ │ │
│ daily: $10.00 │ │ │
│ monthly: $50.00│ │ │
│ channel: alipay│ │ │
│───────────────────►│ │ │
│ │ │ │
│ │ 5. POST /v1/installs │ │
│ │ service_id: ... │ │
│ │ agent_id: ... │ │
│ │ payment_preference │ │
│ │ default_channel: │ │
│ │ "alipay" │ │
│ │ auto_pay_limit: │ │
│ │ {1.00, USD} │ │
│ │ spending_limits: │ │
│ │ {daily: $10, │ │
│ │ monthly: $50} │ │
│ │ webhook_url: ... │ │
│ │───────────────────────►│ │
│ │ │ │
│ │ │ 6. Validate: │
│ │ │ - service_id │
│ │ │ exists/active│
│ │ │ - agent_id │
│ │ │ valid │
│ │ │ - channel │
│ │ │ supported │
│ │ │ - limits │
│ │ │ parse │
│ │ │ │ │
│ │ │ ┌───┴────┐ │
│ │ │ │Channel │ │
│ │ │ │Valid? │ │
│ │ │ └───┬────┘ │
│ │ │ ┌────┴────┐ │
│ │ │ │ yes │ no │
│ │ │ └────┬────┘ │
│ │ │ │ │
│ │ │ 7. Initiate │
│ │ │ Channel Auth │
│ │ │───────────────────►│
│ │ │ │
│ │ │ 8. Auth Request │
│ │ │ (QR / URI) │
│ │◄───────────────────────│ │
│ │ │ │
│ 9. Show QR / │ │ │
│ Auth URI │ │ │
│◄───────────────────│ │ │
│ │ │ │
│ 10. Scan/Authorize│ │ │
│───────────────────►│ │ │
│ │ 11. User confirms │ │
│ │ spending_limits │ │
│ │ (auto_pay_limit │ │
│ │ $1.00) │ │
│───────────────────►│ │ │
│ │ │ │
│ │ 12. POST /v1/installs │ │
│ │ (auth_confirm) │ │
│ │───────────────────────►│ │
│ │ │ 13. Create install│
│ │ │ status: │
│ │ │ "active" │
│ │ │ api_key: │
│ │ │ sk_ins_... │
│ │ │ │
│ │ 14. 201 Created │ │
│ │ install_id, │ │
│ │ api_key, status │ │
│ │◄───────────────────────│ │
│ │ │ │
│ 15. "Smart │ │ │
│ Summary" │ │ │
│ installed ✓ │ │ │
│ Limit: $1.00 │ │ │
│ auto-pay │ │ │
│◄───────────────────│ │ │
│ │ │ │
│ │ ─── AUTO-PAY FLOW AFTER INSTALL ─── │
│ │ │ │
│ │ 16. Agent requests │ │
│ │ service (<=$1) │ │
│ │ │ │
│ │ 17. POST /v1/payments │ │
│ │ (auto=true) │ │
│ │───────────────────────►│ │
│ │ │ 18. Check limits │
│ │ │ ✓ ≤ auto_pay │
│ │ │ ✓ daily OK │
│ │ │ ✓ monthly OK │
│ │ │ │
│ │ │ 19. Process │
│ │ │ auto-payment │
│ │ │───────────────────►│
│ │ │ │ Charge
│ │ │◄────────────────────│ callback
│ │ │ │
│ │ 20. Payment confirmed │ │
│ │◄───────────────────────│ │
│ │ │ │
│ 21. Service used │ │ │
│ ✓ │ │ │
│◄───────────────────│ │ │
│ │ │ │
Edge Cases — Install Lifecycle
┌──────────────┐ ┌──────────────────┐ ┌──────────────┐ ┌──────────────┐
│ Human │ │ Agent │ │ ItPay │ │ Channel │
│ (Payer) │ │ (Buyer) │ │ Protocol │ │ (Alipay) │
└──────┬───────┘ └──────┬───────────┘ └──────┬───────┘ └──────┬───────┘
│ │ │ │
│ EDGE A: Install Rejected (Invalid Channel) │ │
│ │ │ │
│ │ POST /v1/installs │ │
│ │ default_channel: │ │
│ │ "bitcoin" │ │
│ │───────────────────────►│ │
│ │ │ ✗ Channel not │
│ │ │ in manifest's │
│ │ │ accepted_ │
│ │ │ channels │
│ │ HTTP 422 │ │
│ │ UNSUPPORTED_CHANNEL │ │
│ │◄───────────────────────│ │
│ │ │ │
│ EDGE B: Spending Limit Updated │ │
│ │ │ │
│ 22. "Increase │ │ │
│ auto-pay to │ │ │
│ $5.00" │ │ │
│───────────────────►│ │ │
│ │ PATCH /v1/installs/ │ │
│ │ :id │ │
│ │ {auto_pay_limit: $5} │ │
│ │───────────────────────►│ │
│ │ │ Update install │
│ │ │ ✓ Limits updated │
│ │◄───────────────────────│ │
│ 23. "Limit │ │ │
│ updated ✓" │ │ │
│◄───────────────────│ │ │
│ │ │ │
│ EDGE C: Install Suspended (Limit Exceeded)│ │
│ │ │ │
│ │ 24. Auto-pay attempt │ │
│ │ ($12 > $10 daily) │ │
│ │───────────────────────►│ │
│ │ │ ✗ Daily limit │
│ │ │ exceeded ($12 │
│ │ │ > $10 limit) │
│ │ │ │
│ │ │ Set status: │
│ │ │ "suspended" │
│ │ │ Fire webhook: │
│ │ │ install.suspended │
│ │ │ │
│ │ 25. Payment rejected │ │
│ │ (suspended) │ │
│ │◄───────────────────────│ │
│ 26. "Payment │ │ │
│ failed — │ │ │
│ install │ │ │
│ suspended" │ │ │
│◄───────────────────│ │ │
│ │ │ │
│ 27. Human resets │ │ │
│ or waits │ │ │
│ for window │ │ │
│───────────────────►│ │ │
│ │ 28. PATCH /v1/installs│ │
│ │ /:id/reactivate │ │
│ │───────────────────────►│ │
│ │ │ Reset to "active" │
│ │ │ Fire webhook: │
│ │ │ install.reactivated│
│ 29. "Install │ │ │
│ reactivated" │ │ │
│◄───────────────────│ │ │
Swimlane Legend
| Step | Actor | Action | Description |
|---|---|---|---|
| 1 | Agent → Protocol | GET /v1/services | Discover available services by search query |
| 2 | Protocol → Agent | 200 OK | Return matching manifests |
| 3 | Agent → Human | Show service | Present "Smart Summary" to the user for approval |
| 4 | Human → Agent | Confirm install | User approves with spending caps: auto_pay_limit=$1, daily=$10, monthly=$50, channel=alipay |
| 5 | Agent → Protocol | POST /v1/installs | Submit install request with full payment_preference |
| 6 | ItPay Protocol | Validate | Check service_id exists & active, agent_id valid, channel supported, limits parse |
| 7 | Protocol → Channel | Initiate auth | Send channel authorization request |
| 8 | Channel → Agent | Auth request | Return QR code or auth URI |
| 9 | Agent → Human | Show QR | Display authorization prompt to user |
| 10 | Human | Scan/Authorize | User authorizes via their payment app |
| 11 | Human → Agent | Confirm limits | User explicitly confirms spending_limits and auto_pay_limit |
| 12 | Agent → Protocol | Confirm auth | Forward auth confirmation + spending limits |
| 13 | ItPay Protocol | Create install | Set status="active", generate install-scoped api_key |
| 14 | Protocol → Agent | 201 Created | Return install_id, api_key, status, payment_preference |
| 15 | Agent → Human | "Installed ✓" | Confirm to user: Smart Summary installed, auto-pay limit $1.00 |
| 16 | Agent | Service request | Agent requests a service costing ≤ auto_pay_limit ($1) |
| 17 | Agent → Protocol | POST /v1/payments auto=true | Submit auto-pay payment intent |
| 18 | Protocol | Check limits | Verify amount ≤ auto_pay_limit, daily & monthly spending OK |
| 19 | Protocol → Channel | Process payment | Execute payment through the channel |
| 20 | Protocol → Agent | Payment confirmed | Return payment success |
| 21 | Agent → Human | "Service delivered ✓" | Notify user of completed service + payment |
| A | Agent → Protocol | Invalid channel | Install rejected with 422 UNSUPPORTED_CHANNEL |
| B | Human → Agent | Update limits | User requests limit change → PATCH /v1/installs/:id |
| C | Agent → Protocol | Over-limit attempt | Payment > daily limit → status="suspended", webhook fired |
| D | Human → Agent | Reactivate | User resets or waits → PATCH reactivate → "active" restored |
Detailed Interaction Trace
Trace 1: Install a Service (Happy Path)
Human-side dialog:
"I want to install the 'Smart Summary' service with Alipay. Set an auto-pay limit of $1.00 so I don't need to scan a QR for small payments. Cap daily spending at $10 and monthly at $50."
[Human (Payer)] [Agent (Buyer)] [ItPay Protocol] [Channel (Alipay)]
│ │ │ │
│ "Find Smart Summary" │ │ │
│──────────────────────────►│ │ │
│ │ GET /v1/services? │ │
│ │ q=Smart+Summary │ │
│ │──────────────────────────►│ │
│ │ │ Search active manifests │
│ │◄───────────────────────────│ │
│ │ [{name:"Smart Summary", │ │
│ │ id:"01J7XYKZ...", │ │
│ │ accepted_channels: │ │
│ │ ["alipay","wechat"], │ │
│ │ pricing:{one_time:[ │ │
│ │ {amount:99,curency: │ │
│ │ "USD"}]}] │ │
│ │ │ │
│ "Install Smart Summary │ │ │
│ with Alipay. │ │ │
│ Auto-pay: $1.00 │ │ │
│ Daily cap: $10 │ │ │
│ Monthly cap: $50" │ │ │
│──────────────────────────►│ │ │
│ │ │ │
│ │ POST /v1/installs │ │
│ │ { │ │
│ │ "service_id": │ │
│ │ "01J7XYKZ1A2B3C4...", │ │
│ │ "agent_id": │ │
│ │ "agent_cli_a1b2c3d4", │ │
│ │ "payment_preference": { │ │
│ │ "default_channel": │ │
│ │ "alipay", │ │
│ │ "auto_pay_limit": { │ │
│ │ "value": 100, │ │
│ │ "currency": "USD" │ │
│ │ }, │ │
│ │ "spending_limits": { │ │
│ │ "daily": { │ │
│ │ "value": 1000, │ │
│ │ "currency":"USD" │ │
│ │ }, │ │
│ │ "monthly": { │ │
│ │ "value": 5000, │ │
│ │ "currency":"USD" │ │
│ │ } │ │
│ │ } │ │
│ │ }, │ │
│ │ "webhook_url": │ │
│ │ "https://my-agent.ai │ │
│ │ /itpay/webhook" │ │
│ │ } │ │
│ │──────────────────────────►│ │
│ │ │ │
│ │ │ Validate: │
│ │ │ ✓ service_id exists │
│ │ │ ✓ service is active │
│ │ │ ✓ agent_id valid │
│ │ │ ✓ channel "alipay" in │
│ │ │ accepted_channels │
│ │ │ ✓ limits parse correctly│
│ │ │ │
│ │ │ Initiate channel auth │
│ │ │──────────────────────────►│
│ │ │ │
│ │ │ Auth Request │
│ │◄───────────────────────────│ │
│ │ { │ │
│ │ "auth_url": │ │
│ │ "alipay://itpay/ │ │
│ │ auth?token=abc123", │ │
│ │ "qr_code": "data:image/ │ │
│ │ png;base64,..." │ │
│ │ } │ │
│ │ │ │
│ Show QR code │ │ │
│◄──────────────────────────│ │ │
│ │ │ │
│ Scan QR / Open URI │ │ │
│──────────────────────────►│ │ │
│ │ │ │
│ "I confirm the │ │ │
│ spending limits: │ │ │
│ auto-pay max $1, │ │ │
│ daily $10, │ │ │
│ monthly $50" │ │ │
│──────────────────────────►│ │ │
│ │ │ │
│ │ POST /v1/installs │ │
│ │ (auth_confirm) │ │
│ │──────────────────────────►│ │
│ │ │ │
│ │ │ Create install: │
│ │ │ status: "active" │
│ │ │ install_id: │
│ │ │ "inst_01J7Y2A3B4..." │
│ │ │ api_key: "sk_ins_...n4o5"│
│ │ │ │
│ │ HTTP 201 Created │ │
│ │◄───────────────────────────│ │
│ │ { │ │
│ │ "install_id": │ │
│ │ "inst_01J7Y2A3B4C5...",│ │
│ │ "status": "active", │ │
│ │ "api_key": "sk_ins...", │ │
│ │ "payment_preference": { │ │
│ │ "default_channel": │ │
│ │ "alipay", │ │
│ │ "auto_pay_limit": { │ │
│ │ "value": 100, │ │
│ │ "currency": "USD" │ │
│ │ }, │ │
│ │ ... │ │
│ │ } │ │
│ │ } │ │
│ │ │ │
│ "Smart Summary │ │ │
│ installed ✓ │ │ │
│ Auto-pay up to $1.00 │ │ │
│ No QR needed for │ │ │
│ small payments" │ │ │
│◄──────────────────────────│ │ │
Trace 2: Auto-Pay After Install
Human-side dialog:
"Summarize this PDF for me." (No payment interaction needed — the $0.99 is under the $1.00 auto-pay limit.)
[Human (Payer)] [Agent (Buyer)] [ItPay Protocol] [Channel (Alipay)]
│ │ │ │
│ "Summarize this PDF" │ │ │
│──────────────────────────►│ │ │
│ │ │ │
│ │ POST /v1/payments │ │
│ │ { │ │
│ │ "amount": { │ │
│ │ "value": 99, │ │
│ │ "currency": "USD" │ │
│ │ }, │ │
│ │ "auto_pay": true, │ │
│ │ "install_id": │ │
│ │ "inst_01J7Y2A3B4C5...",│ │
│ │ "service_id": │ │
│ │ "01J7XYKZ1A2B3C4..." │ │
│ │ } │ │
│ │──────────────────────────►│ │
│ │ │ │
│ │ │ Auto-pay checks: │
│ │ │ ✓ 99 ≤ 100 (auto_pay) │
│ │ │ ✓ Daily rolling: │
│ │ │ current $8 + $0.99 │
│ │ │ = $8.99 ≤ $10 ✓ │
│ │ │ ✓ Monthly rolling: │
│ │ │ current $32 + $0.99 │
│ │ │ = $32.99 ≤ $50 ✓ │
│ │ │ │
│ │ │ Charge via channel │
│ │ │──────────────────────────►│
│ │ │ │
│ │ │ Payment confirmed │
│ │◄───────────────────────────│ │
│ │ { │ │
│ │ "payment_id": │ │
│ │ "pay_01J7Z...", │ │
│ │ "status": "completed", │ │
│ │ "amount": { │ │
│ │ "value": 99, │ │
│ │ "currency": "USD" │ │
│ │ } │ │
│ │ } │ │
│ │ │ │
│ "Here's your summary ✓ │ │ │
│ Charged $0.99 (auto) │ │ │
│ Daily remaining: $9.01"│ │ │
│◄──────────────────────────│ │ │
Trace 3: Error — Install Rejected (Unsupported Channel)
Human-side dialog:
"I want to install but I only use Bitcoin — let me try that."
[Human (Payer)] [Agent (Buyer)] [ItPay Protocol]
│ │ │
│ "Install with Bitcoin" │ │
│──────────────────────────►│ │
│ │ POST /v1/installs │
│ │ { │
│ │ "service_id": │
│ │ "01J7XYKZ1A2B3C4...", │
│ │ "payment_preference": { │
│ │ "default_channel": │
│ │ "bitcoin", │
│ │ "auto_pay_limit": { │
│ │ "value": 100, │
│ │ "currency": "USD" │
│ │ } │
│ │ } │
│ │ } │
│ │──────────────────────────►│
│ │ │
│ │ │ Validate: │
│ │ │ ✓ service_id exists │
│ │ │ ✓ service is active │
│ │ │ ✗ "bitcoin" NOT in │
│ │ │ accepted_channels │
│ │ │ ["alipay","wechat"] │
│ │ │
│ │ HTTP 422 Unprocessable │
│ │◄───────────────────────────│
│ │ { │
│ │ "error": │
│ │ "validation_error", │
│ │ "code": │
│ │ "UNSUPPORTED_CHANNEL", │
│ │ "field": │
│ │ "payment_preference. │
│ │ default_channel", │
│ │ "message": │
│ │ "\"bitcoin\" is not │
│ │ in the service's │
│ │ accepted_channels. │
│ │ Supported: alipay, │
│ │ wechat." │
│ │ } │
│ │ │
│ "Bitcoin not supported │ │
│ — try Alipay or WeChat"│ │
│◄──────────────────────────│ │
Trace 4: Edge Case — Install Suspended After Limit Exceeded
Human-side dialog:
"I tried to use the service but it says my daily limit was exceeded."
[Human (Payer)] [Agent (Buyer)] [ItPay Protocol] [Channel (Alipay)]
│ │ │ │
│ │ Auto-pay attempt: $12 │ │
│ │ (current daily spend: │ │
│ │ $10, daily limit: $10) │ │
│ │──────────────────────────►│ │
│ │ │ │
│ │ │ Check limits: │
│ │ │ ✓ 1200 ≤ 10000 (auto) │
│ │ │ ✗ $10 + $12 = $22 > │
│ │ │ $10 daily limit │
│ │ │ │
│ │ │ Push notification: │
│ │ │ install.suspended │
│ │ │ ↓ │
│ │ │ Set status: "suspended" │
│ │ │ │
│ │ HTTP 402 Payment Required │ │
│ │◄───────────────────────────│ │
│ │ { │ │
│ │ "error": "limit_ │ │
│ │ exceeded", │ │
│ │ "code": │ │
│ │ "DAILY_LIMIT_EXCEEDED",│ │
│ │ "install_status": │ │
│ │ "suspended", │ │
│ │ "limits": { │ │
│ │ "daily": { │ │
│ │ "value": 1000, │ │
│ │ "spent": 1000, │ │
│ │ "currency": "USD" │ │
│ │ } │ │
│ │ } │ │
│ │ } │ │
│ │ │ │
│ "Payment failed — │ │ │
│ daily limit reached. │ │ │
│ Install suspended." │ │ │
│◄──────────────────────────│ │ │
│ │ │ │
│ "Reset the limits — │ │ │
│ I'll wait for the │ │ │
│ window to reset" │ │ │
│──────────────────────────►│ │ │
│ │ PATCH /v1/installs/ │ │
│ │ inst_01J7Y2A3B4C5.../ │ │
│ │ reactivate │ │
│ │──────────────────────────►│ │
│ │ │ Reset limit window │
│ │ │ Set status: "active" │
│ │ │ Fire webhook: │
│ │ │ install.reactivated │
│ │ │ │
│ │ HTTP 200 OK │ │
│ │◄───────────────────────────│ │
│ │ { "status": "active" } │ │
│ │ │ │
│ "Install reactivated ✓ │ │ │
│ Daily limit reset." │ │ │
│◄──────────────────────────│ │ │
Error Handling Per Step
| Step | Error Condition | HTTP Status | Error Code | Recovery |
|---|---|---|---|---|
| 5 (POST) | Service not found | 404 | SERVICE_NOT_FOUND | Verify service_id from discovery results |
| 5 (POST) | Service not active | 409 | SERVICE_NOT_ACTIVE | Service must be active to install |
| 5 (POST) | Unsupported channel | 422 | UNSUPPORTED_CHANNEL | Choose a channel from manifest's accepted_channels |
| 5 (POST) | Invalid auto_pay limit | 422 | INVALID_AUTO_PAY_LIMIT | Ensure value is positive integer in minor units |
| 5 (POST) | Spending limit format | 422 | INVALID_SPENDING_LIMIT | Follow Money object schema {value, currency} |
| 13 (POST) | Auth confirmation timeout | 408 | AUTH_TIMEOUT | Re-initiate the install request with fresh auth |
| 13 (POST) | User declined auth | 403 | AUTH_DECLINED | Present install option again or abort |
| 17 (auto-pay) | Auto-pay amount exceeds limit | 402 | AUTO_PAY_LIMIT_EXCEEDED | Fall back to QR-prompt or reject; reduce amount |
| 17 (auto-pay) | Daily limit exceeded | 402 | DAILY_LIMIT_EXCEEDED | Install transitions to suspended; wait for window reset or reactivate |
| 17 (auto-pay) | Monthly limit exceeded | 402 | MONTHLY_LIMIT_EXCEEDED | Same as daily; auto-pay blocked until next month |
| 28 (PATCH) | Invalid transition on reactivate | 409 | INVALID_TRANSITION | Only suspended → active is allowed |
| 28 (PATCH) | Install not found | 404 | INSTALL_NOT_FOUND | Verify install_id |
Endpoint
| Method | Endpoint | Description |
|---|---|---|
POST | /v1/installs | Install a service's payment capability |
Request Fields
| Field | Type | Required | Description |
|---|---|---|---|
service_id | string (UUIDv7) | yes | The ServiceManifest id to install |
agent_id | string | yes | Unique identifier of the paying agent |
payment_preference | object | yes | Payment configuration for this installation |
payment_preference.default_channel | string | yes | Default payment channel (e.g. alipay, wechat) |
payment_preference.auto_pay_limit | Money | no | Max single-payment amount for auto-pay (no human interaction) |
payment_preference.spending_limits | object | no | Rolling spending caps |
payment_preference.spending_limits.daily | Money | no | Maximum auto-paid spending per rolling 24-hour window |
payment_preference.spending_limits.monthly | Money | no | Maximum auto-paid spending per calendar month |
webhook_url | string (URL) | no | Optional webhook URL for this installation (overrides manifest endpoint) |
Money Object
| Field | Type | Description |
|---|---|---|
value | number | Amount in minor currency units (e.g. cents) |
currency | string (ISO 4217) | Currency code |
Request Example
POST /v1/installs
Content-Type: application/json
Authorization: Bearer sk_liv_xxxxxxxxxx
{
"service_id": "01J7XYKZ1A2B3C4D5E6F7G8H9I",
"agent_id": "agent_cli_a1b2c3d4",
"payment_preference": {
"default_channel": "alipay",
"auto_pay_limit": {
"value": 100,
"currency": "USD"
},
"spending_limits": {
"daily": {
"value": 1000,
"currency": "USD"
},
"monthly": {
"value": 5000,
"currency": "USD"
}
}
},
"webhook_url": "https://my-agent.ai/itpay/webhook"
}
Response Example
HTTP/1.1 201 Created
Content-Type: application/json
{
"install_id": "inst_01J7Y2A3B4C5D6E7F8G9H0I1J",
"service_id": "01J7XYKZ1A2B3C4D5E6F7G8H9I",
"agent_id": "agent_cli_a1b2c3d4",
"api_key": "sk_inst_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5",
"status": "active",
"payment_preference": {
"default_channel": "alipay",
"auto_pay_limit": {
"value": 100,
"currency": "USD"
},
"spending_limits": {
"daily": {
"value": 1000,
"currency": "USD"
},
"monthly": {
"value": 5000,
"currency": "USD"
}
}
},
"webhook_url": "https://my-agent.ai/itpay/webhook",
"created_at": "2026-05-27T09:05:00Z",
"updated_at": "2026-05-27T09:05:00Z"
}
State Machine
┌───────────┐
│ pending │
└─────┬─────┘
│ activate
▼
┌───────────┐
│ active │
└─────┬─────┘
┌────┴────┐
│ │
▼ ▼
┌────────┐ ┌──────────┐
│suspended│ │uninstalled│
└────────┘ └──────────┘
Transitions
| From | To | Trigger |
|---|---|---|
pending | active | Installation is confirmed and ready for use |
active | suspended | Spending limit exceeded or payment channel issue detected |
active | uninstalled | Agent uninstalls the service (manual or via void) |
suspended | active | Issue resolved (limits reset, channel reconnected) |
suspended | uninstalled | Agent uninstalls while suspended |
Key Behaviors
- API Key per Install: Each successful install generates a unique
api_keyscoped to that installation. This key is used for subsequent payment requests between the payer agent and the service. - Auto-Pay: When
auto_pay_limitis set, payment intents at or below this value complete automatically without human interaction (QR scan). See x402 Semantics for the runtime flow. - Spending Limits:
dailyandmonthlylimits operate on rolling windows. If a limit is exceeded, the install transitions tosuspendedand auto-pay is disabled until the window resets. - Webhook Routing: If
webhook_urlis provided, the service sends installation-scoped events to this URL instead of (or in addition to) the manifest-levelendpoint.
Webhook Events
| Event | Description |
|---|---|
install.suspended | Installation was suspended (limit exceeded or channel error) |
install.reactivated | Installation was reactivated after the issue resolved |
install.uninstalled | Installation was removed |
Next Steps
- Request Payment — Create a QR-based payment intent after install
- One-Time Pay — Simplified instant payment
- x402 Semantics — Auto-pay flow in detail