{
  "openapi": "3.1.0",
  "info": {
    "title": "nett Apps API",
    "version": "1.0.0",
    "summary": "Pay X accounts in X Money from your server, through the nett escrow on Robinhood Chain.",
    "description": "Non-custodial: nett never holds your funds or keys. The API stores your payout intents and returns the calldata your own verified wallet signs and sends (USDG `approve`, escrow `createOrder`, `cancel`, `refund`). The chain is the source of truth: every status comes from the escrow on Robinhood Chain (chain id 4663).\n\n**Server to server.** Programmatic routes take `Authorization: Bearer nett_sk_<keyId>_<secret>`. API keys must never reach a browser: there is no CORS, and a request carrying an API key together with a browser `Origin` or `Sec-Fetch-Site` header is refused (403 `browser_not_allowed`). App management (keys, wallets, webhook) takes a nett sign-in (Privy) access token and is what the Developers console uses.\n\n**Errors** are JSON `{error, message, details?}` with a meaningful HTTP status; `error` is a stable code (see each route). 429 `rate_limited` carries `Retry-After` (best effort: 60 requests a minute per API key; app management, 200 writes an hour per account). 503 codes: `apps_not_configured`, `storage_not_configured`, `storage_unavailable`, `chain_unavailable`, `contract_mismatch`, `privy_not_configured`, `privy_unavailable`, `dispatch_not_configured`.\n\n**Amounts** are decimal strings in US dollars (`\"10.00\"`, at most 2 decimals in requests) with a `...Micros` companion in USDG base units (6 decimals; 1 USD = 1 000 000). Fees are exact (2 to 6 decimals). Times are ISO 8601 (UTC) strings.\n\n**Payout lifecycle.** `awaiting_signature` (send its `calls`) -> `open` (escrowed, waiting for a provider) -> `locked` (a provider holds it and pays in X Money) -> `pending_recipient` (paid, the recipient has not claimed it in X Money yet) -> `settled`. Also `refunded` (deadline passed, nobody filled it), `cancelled` (by you, while nobody held it) and `expired` (never sent before its deadline). `reopened` is a timeline event: the status goes back to `open`.\n\n**Webhooks** (see `webhooks`): POST to your https URL, `Nett-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256(secret, `${t}.${rawBody}`)>` (the key is the whole `whsec_...` string). Reject `|now - t| > 300`. 10 s timeout, 2xx = delivered, no redirect followed, retries after 1 m, 5 m, 30 m, 2 h, 6 h, 24 h, then `dead`. The event id is stable across retries: deduplicate on it. Deliveries may arrive out of order: each carries the whole Payout.\n\nSDK: https://www.usenett.app/sdk/nett.mjs (zero dependency ESM, Node 18+, Deno, Bun).",
    "contact": {
      "url": "https://www.usenett.app/api-docs.html"
    }
  },
  "externalDocs": {
    "description": "nett Apps API guide",
    "url": "https://www.usenett.app/api-docs.html"
  },
  "servers": [
    {
      "url": "https://www.usenett.app"
    }
  ],
  "tags": [
    {
      "name": "Apps",
      "description": "Developer apps, API keys and payer wallets (nett sign-in)."
    },
    {
      "name": "Webhooks",
      "description": "Webhook endpoint, secret and deliveries (nett sign-in)."
    },
    {
      "name": "Payouts",
      "description": "Programmatic payouts (API key, server side only)."
    },
    {
      "name": "Scheduler",
      "description": "The webhook dispatcher trigger for an external scheduler."
    }
  ],
  "paths": {
    "/api/v1/apps": {
      "get": {
        "tags": [
          "Apps"
        ],
        "operationId": "listApps",
        "summary": "Your apps",
        "security": [
          {
            "privyBearer": []
          }
        ],
        "responses": {
          "200": {
            "description": "Your apps, oldest first.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "apps"
                  ],
                  "properties": {
                    "apps": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/App"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      },
      "post": {
        "tags": [
          "Apps"
        ],
        "operationId": "createApp",
        "summary": "Create an app (5 per account at most)",
        "security": [
          {
            "privyBearer": []
          }
        ],
        "description": "Errors: 400 `invalid_name`, 409 `too_many_apps` {details: {max}}, 403 `bad_origin` (a browser on another origin).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 64
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "app"
                  ],
                  "properties": {
                    "app": {
                      "$ref": "#/components/schemas/App"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/api/v1/apps/{appId}": {
      "parameters": [
        {
          "name": "appId",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "pattern": "^app_[a-z0-9]{10}$"
          },
          "example": "app_k3j9x0q2m1"
        }
      ],
      "get": {
        "tags": [
          "Apps"
        ],
        "operationId": "getApp",
        "summary": "One app",
        "security": [
          {
            "privyBearer": []
          }
        ],
        "responses": {
          "200": {
            "description": "The app.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "app"
                  ],
                  "properties": {
                    "app": {
                      "$ref": "#/components/schemas/App"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      },
      "patch": {
        "tags": [
          "Apps"
        ],
        "operationId": "renameApp",
        "summary": "Rename an app",
        "security": [
          {
            "privyBearer": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 64
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Renamed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "app"
                  ],
                  "properties": {
                    "app": {
                      "$ref": "#/components/schemas/App"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      },
      "delete": {
        "tags": [
          "Apps"
        ],
        "operationId": "deleteApp",
        "summary": "Delete an app",
        "security": [
          {
            "privyBearer": []
          }
        ],
        "description": "Revokes every key, removes the webhook (pending deliveries are dropped) and releases the wallets for other apps. The app id is never reused. 404 `app_not_found` for an app that is not yours (or no longer exists).",
        "responses": {
          "204": {
            "description": "Deleted."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/api/v1/apps/{appId}/keys": {
      "parameters": [
        {
          "name": "appId",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "pattern": "^app_[a-z0-9]{10}$"
          },
          "example": "app_k3j9x0q2m1"
        }
      ],
      "post": {
        "tags": [
          "Apps"
        ],
        "operationId": "createKey",
        "summary": "Create an API key (shown once)",
        "security": [
          {
            "privyBearer": []
          }
        ],
        "description": "The key is returned once and stored only as sha256(secret): keep it in your server's secret store. 5 active keys per app at most (409 `too_many_keys`). 503 `apps_not_configured` while the deployment has no APPS_ENCRYPTION_KEY.",
        "responses": {
          "201": {
            "description": "The new key.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "key",
                    "keyId",
                    "createdAt"
                  ],
                  "properties": {
                    "key": {
                      "type": "string",
                      "pattern": "^nett_sk_[a-z0-9]{8}_[A-Za-z0-9_-]{43}$"
                    },
                    "keyId": {
                      "type": "string",
                      "pattern": "^[a-z0-9]{8}$"
                    },
                    "createdAt": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/api/v1/apps/{appId}/keys/{keyId}": {
      "parameters": [
        {
          "name": "appId",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "pattern": "^app_[a-z0-9]{10}$"
          },
          "example": "app_k3j9x0q2m1"
        },
        {
          "name": "keyId",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "pattern": "^[a-z0-9]{8}$"
          }
        }
      ],
      "delete": {
        "tags": [
          "Apps"
        ],
        "operationId": "revokeKey",
        "summary": "Revoke an API key",
        "security": [
          {
            "privyBearer": []
          }
        ],
        "description": "Effective at once on the instance that revoked it, within 15 s everywhere. Revoking twice is a no-op (204); 404 `key_not_found`.",
        "responses": {
          "204": {
            "description": "Revoked."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/api/v1/apps/{appId}/wallets/challenge": {
      "parameters": [
        {
          "name": "appId",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "pattern": "^app_[a-z0-9]{10}$"
          },
          "example": "app_k3j9x0q2m1"
        }
      ],
      "post": {
        "tags": [
          "Apps"
        ],
        "operationId": "walletChallenge",
        "summary": "Challenge for a payer wallet",
        "security": [
          {
            "privyBearer": []
          }
        ],
        "description": "Sign `message` exactly (EIP-191 personal_sign) with the wallet, then POST it to `/wallets` before `expiresAt` (10 minutes). Each challenge works once. Errors: 400 `invalid_address`, 409 `wallet_exists` | `wallet_in_other_app` | `too_many_wallets` (10 per app).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "address"
                ],
                "properties": {
                  "address": {
                    "type": "string",
                    "pattern": "^0x[0-9a-fA-F]{40}$",
                    "example": "0x70085048eCa377619e9584605e5C30868a7890E6"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The message to sign: \"nett: app <appId> controls wallet <checksummed address>\\nNonce: <nonce>\\nExpires: <ISO>\".",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "message",
                    "nonce",
                    "expiresAt"
                  ],
                  "properties": {
                    "message": {
                      "type": "string",
                      "example": "nett: app app_k3j9x0q2m1 controls wallet 0x1234567890AbcdEF1234567890aBcdef12345678\nNonce: 7f3c9d0a1b2e4f5a6b7c8d9e0f1a2b3c\nExpires: 2026-10-01T12:10:00.000Z"
                    },
                    "nonce": {
                      "type": "string",
                      "pattern": "^[0-9a-f]{32}$"
                    },
                    "expiresAt": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/api/v1/apps/{appId}/wallets": {
      "parameters": [
        {
          "name": "appId",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "pattern": "^app_[a-z0-9]{10}$"
          },
          "example": "app_k3j9x0q2m1"
        }
      ],
      "post": {
        "tags": [
          "Apps"
        ],
        "operationId": "verifyWallet",
        "summary": "Verify a payer wallet",
        "security": [
          {
            "privyBearer": []
          }
        ],
        "description": "EIP-191 personal_sign of the exact challenge message. An EOA is checked by signature recovery; a smart account (deployed on chain 4663) by ERC-1271 `isValidSignature(hashMessage(message), signature)`. A wallet belongs to one app at most. Errors: 400 `invalid_address` | `invalid_signature` | `challenge_not_found` (none, or already used) | `challenge_expired`; 409 `wallet_exists` | `wallet_in_other_app` | `too_many_wallets`; 503 `chain_unavailable` (smart account check).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "address",
                  "signature"
                ],
                "properties": {
                  "address": {
                    "type": "string",
                    "pattern": "^0x[0-9a-fA-F]{40}$",
                    "example": "0x70085048eCa377619e9584605e5C30868a7890E6"
                  },
                  "signature": {
                    "type": "string",
                    "pattern": "^0x[0-9a-fA-F]*$"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Verified.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "wallet"
                  ],
                  "properties": {
                    "wallet": {
                      "$ref": "#/components/schemas/Wallet"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/api/v1/apps/{appId}/wallets/{address}": {
      "parameters": [
        {
          "name": "appId",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "pattern": "^app_[a-z0-9]{10}$"
          },
          "example": "app_k3j9x0q2m1"
        },
        {
          "name": "address",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "pattern": "^0x[0-9a-fA-F]{40}$",
            "example": "0x70085048eCa377619e9584605e5C30868a7890E6"
          }
        }
      ],
      "delete": {
        "tags": [
          "Apps"
        ],
        "operationId": "removeWallet",
        "summary": "Remove a payer wallet",
        "security": [
          {
            "privyBearer": []
          }
        ],
        "description": "404 `wallet_not_found`. Orders it already created keep their status; new payouts can no longer use it.",
        "responses": {
          "204": {
            "description": "Removed."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/api/v1/apps/{appId}/webhook": {
      "parameters": [
        {
          "name": "appId",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "pattern": "^app_[a-z0-9]{10}$"
          },
          "example": "app_k3j9x0q2m1"
        }
      ],
      "put": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "setWebhook",
        "summary": "Set the webhook URL",
        "security": [
          {
            "privyBearer": []
          }
        ],
        "description": "https only, default port, 443 or 8443, no credentials, no fragment, and the host must resolve to public addresses only (checked again at every delivery: no private, loopback, link-local, CGNAT, multicast, metadata or IPv6 ULA / link-local address). 201 with the `secret` when the webhook is created; 200 without it on an update (the secret is unchanged; POST .../rotate for a new one). Errors: 400 `invalid_webhook_url` {details: {field: \"url\", reason: https_required | credentials_not_allowed | port_not_allowed | fragment_not_allowed | private_address | unresolvable | invalid}}, 400 `invalid_request` (enabled), 503 `apps_not_configured`.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "url"
                ],
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "maxLength": 2048,
                    "example": "https://api.example.com/nett/webhook"
                  },
                  "enabled": {
                    "type": "boolean",
                    "default": true,
                    "description": "false: no event is enqueued for the app, pending deliveries die at their next attempt."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "webhook"
                  ],
                  "properties": {
                    "webhook": {
                      "$ref": "#/components/schemas/Webhook"
                    }
                  }
                }
              }
            }
          },
          "201": {
            "description": "Created: the secret is shown this once.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "webhook"
                  ],
                  "properties": {
                    "webhook": {
                      "$ref": "#/components/schemas/WebhookWithSecret"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      },
      "delete": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "deleteWebhook",
        "summary": "Remove the webhook",
        "security": [
          {
            "privyBearer": []
          }
        ],
        "description": "Pending deliveries are marked dead (`no_webhook`) at their next attempt. Idempotent.",
        "responses": {
          "204": {
            "description": "Removed."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/api/v1/apps/{appId}/webhook/rotate": {
      "parameters": [
        {
          "name": "appId",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "pattern": "^app_[a-z0-9]{10}$"
          },
          "example": "app_k3j9x0q2m1"
        }
      ],
      "post": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "rotateWebhookSecret",
        "summary": "New webhook secret (shown once)",
        "security": [
          {
            "privyBearer": []
          }
        ],
        "description": "Every delivery from now on, retries included, is signed with the new secret. 404 `webhook_not_found`.",
        "responses": {
          "200": {
            "description": "The new secret.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "secret"
                  ],
                  "properties": {
                    "secret": {
                      "type": "string",
                      "pattern": "^whsec_[A-Za-z0-9_-]{43}$"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/api/v1/apps/{appId}/webhook/test": {
      "parameters": [
        {
          "name": "appId",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "pattern": "^app_[a-z0-9]{10}$"
          },
          "example": "app_k3j9x0q2m1"
        }
      ],
      "post": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "testWebhook",
        "summary": "Send a ping now",
        "security": [
          {
            "privyBearer": []
          }
        ],
        "description": "One signed `ping` event, sent synchronously and recorded; a failed ping is not retried. 404 `webhook_not_found`; 429 after 10 a minute.",
        "responses": {
          "200": {
            "description": "The delivery, with its outcome.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "delivery"
                  ],
                  "properties": {
                    "delivery": {
                      "$ref": "#/components/schemas/Delivery"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/api/v1/apps/{appId}/deliveries": {
      "parameters": [
        {
          "name": "appId",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "pattern": "^app_[a-z0-9]{10}$"
          },
          "example": "app_k3j9x0q2m1"
        },
        {
          "name": "limit",
          "in": "query",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "default": 50
          }
        }
      ],
      "get": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "listDeliveries",
        "summary": "Recent deliveries, newest first",
        "security": [
          {
            "privyBearer": []
          }
        ],
        "description": "Every unfinished delivery plus the last 100 finished ones of the last 30 days. 400 `invalid_limit`.",
        "responses": {
          "200": {
            "description": "Deliveries.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "deliveries"
                  ],
                  "properties": {
                    "deliveries": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Delivery"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/api/v1/apps/{appId}/deliveries/{deliveryId}/resend": {
      "parameters": [
        {
          "name": "appId",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "pattern": "^app_[a-z0-9]{10}$"
          },
          "example": "app_k3j9x0q2m1"
        },
        {
          "name": "deliveryId",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "pattern": "^dlv_[a-z0-9]{12}$"
          }
        }
      ],
      "post": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "resendDelivery",
        "summary": "Send a delivery again now",
        "security": [
          {
            "privyBearer": []
          }
        ],
        "description": "The same event (same id, same body), freshly signed, one attempt now. A success marks it succeeded; a failure keeps an automatic retry already planned and plans none otherwise. 404 `delivery_not_found` | `webhook_not_found`.",
        "responses": {
          "200": {
            "description": "The delivery after the attempt.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "delivery"
                  ],
                  "properties": {
                    "delivery": {
                      "$ref": "#/components/schemas/Delivery"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/api/v1/quote": {
      "get": {
        "tags": [
          "Payouts"
        ],
        "operationId": "quote",
        "summary": "Providers and fees for an amount",
        "security": [
          {
            "apiKey": []
          }
        ],
        "description": "Active providers = registered, not blocked, free bond and tier cap both covering the amount. `suggestedMaxFee` covers every active provider's fee (floor(amount x bps / 10 000), rounded up to the cent; 1 % when none is active): you only ever pay the fee of the provider that takes the payout, the rest comes back at the fill. Errors: 400 `invalid_amount`, 422 `amount_too_low` | `amount_above_max`.",
        "parameters": [
          {
            "name": "amount",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^\\d{1,12}(\\.\\d{1,2})?$",
              "example": "10.00"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The quote.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Quote"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/api/v1/payouts": {
      "post": {
        "tags": [
          "Payouts"
        ],
        "operationId": "createPayouts",
        "summary": "Create payouts (1 to 50)",
        "security": [
          {
            "apiKey": []
          }
        ],
        "description": "Creates the payout intents and returns, for each, the `calls` to sign and send from `from`, plus the USDG `approve` they need. Nothing moves until you send them. All or nothing: one invalid or conflicting payout rejects the request (`details.index` says which).\n\n**Idempotent** per (app, externalId): the same parameters as given return the same payout (200, nothing written); other parameters are a 409 `externalId_conflict`. The chain is not idempotent: a createOrder sent twice escrows twice (the first order is the payout's; cancel the other).\n\n**Recipient.** `xUserId` is what is paid. Without it, `handle` must belong to a nett user who allows discovery (else 422 `unknown_handle`); with both, a handle that belongs to another account is a 422 `handle_mismatch`. Ids are never guessed. Without a handle, the order's display handle on chain is the numeric id (the Payout's `handle` is null).\n\n**One wallet per request** (422 `mixed_from`): `approve` is that wallet's. It covers every payout of this app still awaiting a signature from that wallet (approve SETS the allowance); the escrow only pulls from the wallet calling createOrder.\n\n201 when at least one payout was created, else 200. Errors (422 unless noted, with details {index, externalId, field}): `invalid_external_id`, `invalid_from`, `wallet_not_verified`, `mixed_from`, `duplicate_external_id`, `invalid_amount`, `amount_too_low`, `amount_above_max`, `invalid_max_fee`, `max_fee_above_amount`, `invalid_deadline`, `deadline_out_of_range`, `invalid_x_user_id`, `invalid_handle`, `recipient_required`, `unknown_handle`, `handle_mismatch`; 400 `invalid_request` (not 1 to 50 payouts); 409 `externalId_conflict`; 409 `too_many_payouts` {details: {max, stored}} (at most 5,000 payouts per app: nothing created); 429 `rate_limited` (also when the app looked up more than 100 new handles in a minute: pass `xUserId`); 503 `privy_unavailable` (a handle could not be checked: nothing created).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "payouts"
                ],
                "properties": {
                  "payouts": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 50,
                    "items": {
                      "$ref": "#/components/schemas/PayoutInput"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Every payout already existed with these parameters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreatePayoutsResponse"
                }
              }
            }
          },
          "201": {
            "description": "At least one payout was created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreatePayoutsResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      },
      "get": {
        "tags": [
          "Payouts"
        ],
        "operationId": "listPayouts",
        "summary": "Your payouts, newest first",
        "security": [
          {
            "apiKey": []
          }
        ],
        "description": "Errors: 400 `invalid_status` | `invalid_limit` | `invalid_cursor`.",
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/PayoutStatus"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "`nextCursor` of the previous page."
          }
        ],
        "responses": {
          "200": {
            "description": "A page.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "payouts",
                    "nextCursor"
                  ],
                  "properties": {
                    "payouts": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Payout"
                      }
                    },
                    "nextCursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/api/v1/payouts/confirm": {
      "post": {
        "tags": [
          "Payouts"
        ],
        "operationId": "confirmPayouts",
        "summary": "Link the orders a transaction created",
        "security": [
          {
            "apiKey": []
          }
        ],
        "description": "Reads the receipt on chain 4663. Each OrderCreated from one of this app's wallets whose ref is one of its payouts and whose parameters are exactly that payout's is linked (idempotent). Orders from this app's wallets it did not link are listed in `ignored`. Webhooks and the event index link orders without it; confirming makes the link immediate. Errors: 400 `invalid_tx_hash`, 404 `tx_not_found` (not mined yet: retry), 422 `tx_reverted`.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "txHash"
                ],
                "properties": {
                  "txHash": {
                    "type": "string",
                    "pattern": "^0x[0-9a-fA-F]{64}$"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Linked payouts.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "payouts",
                    "ignored"
                  ],
                  "properties": {
                    "payouts": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Payout"
                      }
                    },
                    "ignored": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/IgnoredOrder"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/api/v1/payouts/{externalId}": {
      "parameters": [
        {
          "name": "externalId",
          "in": "path",
          "required": true,
          "description": "Your id for the payout (URL-encode it: it may contain \":\").",
          "schema": {
            "$ref": "#/components/schemas/ExternalId"
          }
        }
      ],
      "get": {
        "tags": [
          "Payouts"
        ],
        "operationId": "getPayout",
        "summary": "One payout (live status)",
        "security": [
          {
            "apiKey": []
          }
        ],
        "description": "404 `payout_not_found` (also for another app's externalId).",
        "responses": {
          "200": {
            "description": "The payout.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "payout"
                  ],
                  "properties": {
                    "payout": {
                      "$ref": "#/components/schemas/Payout"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/api/v1/payouts/{externalId}/cancel": {
      "parameters": [
        {
          "name": "externalId",
          "in": "path",
          "required": true,
          "description": "Your id for the payout (URL-encode it: it may contain \":\").",
          "schema": {
            "$ref": "#/components/schemas/ExternalId"
          }
        }
      ],
      "post": {
        "tags": [
          "Payouts"
        ],
        "operationId": "cancelPayout",
        "summary": "Calldata to cancel",
        "security": [
          {
            "apiKey": []
          }
        ],
        "description": "Only when the contract allows a cancel now, simulated from the payer: the order is open (or a provider's lock has lapsed). It credits amount + max fee to the payer IN the escrow: the escrow's `withdraw()` moves it to the wallet. Errors: 404 `payout_not_found`, 409 `no_order` (nothing on chain yet) | `not_cancellable` {details: {reason (the contract error), status}}.",
        "responses": {
          "200": {
            "description": "The call to send from the payer wallet.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CallsResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/api/v1/payouts/{externalId}/refund": {
      "parameters": [
        {
          "name": "externalId",
          "in": "path",
          "required": true,
          "description": "Your id for the payout (URL-encode it: it may contain \":\").",
          "schema": {
            "$ref": "#/components/schemas/ExternalId"
          }
        }
      ],
      "post": {
        "tags": [
          "Payouts"
        ],
        "operationId": "refundPayout",
        "summary": "Calldata to refund",
        "security": [
          {
            "apiKey": []
          }
        ],
        "description": "Only when the contract allows a refund now (deadline passed, nobody holds the order), simulated. Credits amount + max fee to the payer in the escrow (`withdraw()` moves it). Errors: 404 `payout_not_found`, 409 `no_order` | `not_refundable` {details: {reason, status}}.",
        "responses": {
          "200": {
            "description": "The call (anyone may send it; the money always goes to the payer).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CallsResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/api/v1/dispatch": {
      "post": {
        "tags": [
          "Scheduler"
        ],
        "operationId": "dispatch",
        "summary": "Run the webhook dispatcher",
        "security": [
          {
            "dispatchSecret": []
          }
        ],
        "description": "For an external scheduler (every 30 minutes). Syncs the escrow events, enqueues the deliveries and sends what is due. Never two runs at once (a lease). `?async=1` answers 202 at once and runs after. Errors: 401 `unauthorized`, 503 `dispatch_not_configured` | `apps_not_configured` | `chain_unavailable` | `storage_unavailable`.",
        "parameters": [
          {
            "name": "async",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            }
          },
          {
            "name": "force",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            },
            "description": "Read the dispatcher state even when this instance knows nothing changed."
          }
        ],
        "responses": {
          "200": {
            "description": "The run: counts only.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DispatchSummary"
                }
              }
            }
          },
          "202": {
            "description": "Accepted (async).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "accepted"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "accepted": {
                      "const": true
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    }
  },
  "webhooks": {
    "payout.created": {
      "post": {
        "summary": "Sent when the payout's order emits OrderCreated",
        "description": "Verify `Nett-Signature` on the raw body before parsing (SDK: verifyWebhook). Answer 2xx within 10 s. The payout in `data` is the Payout as of this event.",
        "parameters": [
          {
            "name": "Nett-Event",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "const": "payout.created"
            }
          },
          {
            "name": "Nett-Delivery",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^dlv_[a-z0-9]{12}$"
            }
          },
          {
            "name": "Nett-Signature",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^t=\\d+,v1=[0-9a-f]{64}$"
            },
            "description": "t=<unix seconds>,v1=<hex HMAC-SHA256(secret, `${t}.${rawBody}`)>"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/PayoutEvent"
                  },
                  {
                    "properties": {
                      "type": {
                        "const": "payout.created"
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "2XX": {
            "description": "Delivered. Anything else (or no answer within 10 s) is retried."
          }
        }
      }
    },
    "payout.locked": {
      "post": {
        "summary": "Sent when the payout's order emits OrderLocked",
        "description": "Verify `Nett-Signature` on the raw body before parsing (SDK: verifyWebhook). Answer 2xx within 10 s. The payout in `data` is the Payout as of this event.",
        "parameters": [
          {
            "name": "Nett-Event",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "const": "payout.locked"
            }
          },
          {
            "name": "Nett-Delivery",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^dlv_[a-z0-9]{12}$"
            }
          },
          {
            "name": "Nett-Signature",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^t=\\d+,v1=[0-9a-f]{64}$"
            },
            "description": "t=<unix seconds>,v1=<hex HMAC-SHA256(secret, `${t}.${rawBody}`)>"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/PayoutEvent"
                  },
                  {
                    "properties": {
                      "type": {
                        "const": "payout.locked"
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "2XX": {
            "description": "Delivered. Anything else (or no answer within 10 s) is retried."
          }
        }
      }
    },
    "payout.pending_recipient": {
      "post": {
        "summary": "Sent when the payout's order emits PaymentPending",
        "description": "Verify `Nett-Signature` on the raw body before parsing (SDK: verifyWebhook). Answer 2xx within 10 s. The payout in `data` is the Payout as of this event.",
        "parameters": [
          {
            "name": "Nett-Event",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "const": "payout.pending_recipient"
            }
          },
          {
            "name": "Nett-Delivery",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^dlv_[a-z0-9]{12}$"
            }
          },
          {
            "name": "Nett-Signature",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^t=\\d+,v1=[0-9a-f]{64}$"
            },
            "description": "t=<unix seconds>,v1=<hex HMAC-SHA256(secret, `${t}.${rawBody}`)>"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/PayoutEvent"
                  },
                  {
                    "properties": {
                      "type": {
                        "const": "payout.pending_recipient"
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "2XX": {
            "description": "Delivered. Anything else (or no answer within 10 s) is retried."
          }
        }
      }
    },
    "payout.reopened": {
      "post": {
        "summary": "Sent when the payout's order emits OrderReopened",
        "description": "Verify `Nett-Signature` on the raw body before parsing (SDK: verifyWebhook). Answer 2xx within 10 s. The payout in `data` is the Payout as of this event.",
        "parameters": [
          {
            "name": "Nett-Event",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "const": "payout.reopened"
            }
          },
          {
            "name": "Nett-Delivery",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^dlv_[a-z0-9]{12}$"
            }
          },
          {
            "name": "Nett-Signature",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^t=\\d+,v1=[0-9a-f]{64}$"
            },
            "description": "t=<unix seconds>,v1=<hex HMAC-SHA256(secret, `${t}.${rawBody}`)>"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/PayoutEvent"
                  },
                  {
                    "properties": {
                      "type": {
                        "const": "payout.reopened"
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "2XX": {
            "description": "Delivered. Anything else (or no answer within 10 s) is retried."
          }
        }
      }
    },
    "payout.settled": {
      "post": {
        "summary": "Sent when the payout's order emits OrderFilled",
        "description": "Verify `Nett-Signature` on the raw body before parsing (SDK: verifyWebhook). Answer 2xx within 10 s. The payout in `data` is the Payout as of this event.",
        "parameters": [
          {
            "name": "Nett-Event",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "const": "payout.settled"
            }
          },
          {
            "name": "Nett-Delivery",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^dlv_[a-z0-9]{12}$"
            }
          },
          {
            "name": "Nett-Signature",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^t=\\d+,v1=[0-9a-f]{64}$"
            },
            "description": "t=<unix seconds>,v1=<hex HMAC-SHA256(secret, `${t}.${rawBody}`)>"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/PayoutEvent"
                  },
                  {
                    "properties": {
                      "type": {
                        "const": "payout.settled"
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "2XX": {
            "description": "Delivered. Anything else (or no answer within 10 s) is retried."
          }
        }
      }
    },
    "payout.refunded": {
      "post": {
        "summary": "Sent when the payout's order emits OrderRefunded",
        "description": "Verify `Nett-Signature` on the raw body before parsing (SDK: verifyWebhook). Answer 2xx within 10 s. The payout in `data` is the Payout as of this event.",
        "parameters": [
          {
            "name": "Nett-Event",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "const": "payout.refunded"
            }
          },
          {
            "name": "Nett-Delivery",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^dlv_[a-z0-9]{12}$"
            }
          },
          {
            "name": "Nett-Signature",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^t=\\d+,v1=[0-9a-f]{64}$"
            },
            "description": "t=<unix seconds>,v1=<hex HMAC-SHA256(secret, `${t}.${rawBody}`)>"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/PayoutEvent"
                  },
                  {
                    "properties": {
                      "type": {
                        "const": "payout.refunded"
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "2XX": {
            "description": "Delivered. Anything else (or no answer within 10 s) is retried."
          }
        }
      }
    },
    "payout.cancelled": {
      "post": {
        "summary": "Sent when the payout's order emits OrderCancelled",
        "description": "Verify `Nett-Signature` on the raw body before parsing (SDK: verifyWebhook). Answer 2xx within 10 s. The payout in `data` is the Payout as of this event.",
        "parameters": [
          {
            "name": "Nett-Event",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "const": "payout.cancelled"
            }
          },
          {
            "name": "Nett-Delivery",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^dlv_[a-z0-9]{12}$"
            }
          },
          {
            "name": "Nett-Signature",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^t=\\d+,v1=[0-9a-f]{64}$"
            },
            "description": "t=<unix seconds>,v1=<hex HMAC-SHA256(secret, `${t}.${rawBody}`)>"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/PayoutEvent"
                  },
                  {
                    "properties": {
                      "type": {
                        "const": "payout.cancelled"
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "2XX": {
            "description": "Delivered. Anything else (or no answer within 10 s) is retried."
          }
        }
      }
    },
    "ping": {
      "post": {
        "summary": "Test event (POST .../webhook/test)",
        "description": "Verify `Nett-Signature` on the raw body before parsing (SDK: verifyWebhook). Answer 2xx within 10 s. The payout in `data` is the Payout as of this event.",
        "parameters": [
          {
            "name": "Nett-Event",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "const": "ping"
            }
          },
          {
            "name": "Nett-Delivery",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^dlv_[a-z0-9]{12}$"
            }
          },
          {
            "name": "Nett-Signature",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^t=\\d+,v1=[0-9a-f]{64}$"
            },
            "description": "t=<unix seconds>,v1=<hex HMAC-SHA256(secret, `${t}.${rawBody}`)>"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PingEvent"
              }
            }
          }
        },
        "responses": {
          "2XX": {
            "description": "Delivered. Anything else (or no answer within 10 s) is retried."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "privyBearer": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "A nett sign-in (Privy) access token: the Developers console."
      },
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "nett_sk_<keyId>_<secret>",
        "description": "An API key (server side only)."
      },
      "dispatchSecret": {
        "type": "http",
        "scheme": "bearer",
        "description": "DISPATCH_SECRET of the deployment."
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Malformed request (invalid_json, unsupported_media_type, body_too_large, or the route's codes).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Missing or invalid credentials: missing_token | invalid_token | token_expired | unknown_user | api_key_not_allowed (management) · missing_api_key | invalid_api_key | revoked_api_key (programmatic) · unauthorized (dispatch).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        },
        "headers": {
          "WWW-Authenticate": {
            "schema": {
              "type": "string",
              "const": "Bearer"
            }
          }
        }
      },
      "Forbidden": {
        "description": "browser_not_allowed (an API key from a browser) · bad_origin (a management write from another origin).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "NotFound": {
        "description": "not_found, app_not_found, key_not_found, wallet_not_found, webhook_not_found, delivery_not_found, payout_not_found, tx_not_found.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "MethodNotAllowed": {
        "description": "method_not_allowed (Allow header lists the methods).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Conflict": {
        "description": "A state conflict (see the route), or `conflict`: concurrent changes, retry.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Unprocessable": {
        "description": "A well-formed request the API cannot accept (see the route).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "RateLimited": {
        "description": "rate_limited.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        },
        "headers": {
          "Retry-After": {
            "schema": {
              "type": "integer"
            },
            "description": "Seconds."
          }
        }
      },
      "Unavailable": {
        "description": "A dependency is not configured or not reachable: retry later.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error",
          "message"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "Stable error code.",
            "example": "externalId_conflict"
          },
          "message": {
            "type": "string"
          },
          "details": {
            "type": "object",
            "additionalProperties": true,
            "description": "Where it applies: {index, externalId, field} for a payout, {reason, status} for cancel / refund, {field, reason} for a webhook URL, {max} for limits."
          },
          "retryAfter": {
            "type": "integer",
            "description": "429 only (seconds)."
          }
        }
      },
      "App": {
        "type": "object",
        "required": [
          "id",
          "name",
          "createdAt",
          "wallets",
          "keys",
          "webhook"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^app_[a-z0-9]{10}$"
          },
          "name": {
            "type": "string"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "wallets": {
            "type": "array",
            "maxItems": 10,
            "items": {
              "$ref": "#/components/schemas/Wallet"
            }
          },
          "keys": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/KeyInfo"
            },
            "description": "Active keys (5 at most) and the last revoked ones. Never the secret."
          },
          "webhook": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Webhook"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "Wallet": {
        "type": "object",
        "required": [
          "address",
          "verifiedAt"
        ],
        "properties": {
          "address": {
            "type": "string",
            "pattern": "^0x[0-9a-fA-F]{40}$",
            "example": "0x70085048eCa377619e9584605e5C30868a7890E6"
          },
          "verifiedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "KeyInfo": {
        "type": "object",
        "required": [
          "keyId",
          "createdAt",
          "lastUsedAt",
          "revokedAt"
        ],
        "properties": {
          "keyId": {
            "type": "string",
            "pattern": "^[a-z0-9]{8}$"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "lastUsedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Approximate: written at most every 6 hours."
          },
          "revokedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        }
      },
      "Webhook": {
        "type": "object",
        "required": [
          "url",
          "enabled",
          "createdAt"
        ],
        "properties": {
          "url": {
            "type": "string",
            "format": "uri"
          },
          "enabled": {
            "type": "boolean"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "WebhookWithSecret": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Webhook"
          },
          {
            "type": "object",
            "required": [
              "secret"
            ],
            "properties": {
              "secret": {
                "type": "string",
                "pattern": "^whsec_[A-Za-z0-9_-]{43}$",
                "description": "Shown once. HMAC key of Nett-Signature (the whole string, UTF-8)."
              }
            }
          }
        ]
      },
      "Delivery": {
        "type": "object",
        "required": [
          "id",
          "eventId",
          "type",
          "status",
          "attempts",
          "nextAttemptAt",
          "lastStatusCode",
          "lastError",
          "createdAt",
          "deliveredAt"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^dlv_[a-z0-9]{12}$"
          },
          "eventId": {
            "type": "string",
            "pattern": "^evt_[0-9a-f]{16}$"
          },
          "type": {
            "type": "string",
            "enum": [
              "ping",
              "payout.created",
              "payout.locked",
              "payout.pending_recipient",
              "payout.reopened",
              "payout.settled",
              "payout.refunded",
              "payout.cancelled"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "succeeded",
              "failed",
              "dead"
            ],
            "description": "pending: not attempted yet. failed: the last attempt failed; retried at nextAttemptAt when it is set (a failed ping or manual resend is not). dead: every retry failed, or the webhook was removed / disabled."
          },
          "attempts": {
            "type": "integer",
            "minimum": 0
          },
          "nextAttemptAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "lastStatusCode": {
            "type": [
              "integer",
              "null"
            ],
            "description": "HTTP status of the last answer (null: no answer)."
          },
          "lastError": {
            "type": [
              "string",
              "null"
            ],
            "description": "http_<status>, redirect_not_followed, timeout, dns_failed, connection_failed, tls_error, blocked_address (the host resolved to a non-public address), network_error, no_webhook, webhook_disabled, secret_unreadable (a deployment key problem: postponed an hour, no retry used), backlog_full (500 deliveries of this app were already waiting: recorded dead, never sent automatically; resend it)."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "deliveredAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        }
      },
      "ExternalId": {
        "type": "string",
        "pattern": "^[A-Za-z0-9_.:-]{1,64}$",
        "description": "Your id (1 to 64 of A-Z a-z 0-9 _ . : -, not only dots). Unique per app.",
        "example": "order_1042"
      },
      "PayoutStatus": {
        "type": "string",
        "enum": [
          "awaiting_signature",
          "open",
          "locked",
          "pending_recipient",
          "settled",
          "refunded",
          "cancelled",
          "expired"
        ]
      },
      "PayoutInput": {
        "type": "object",
        "required": [
          "externalId",
          "from",
          "amount"
        ],
        "properties": {
          "externalId": {
            "$ref": "#/components/schemas/ExternalId"
          },
          "from": {
            "type": "string",
            "pattern": "^0x[0-9a-fA-F]{40}$",
            "example": "0x70085048eCa377619e9584605e5C30868a7890E6",
            "description": "A wallet verified in this app: it signs and sends the calls, and receives refunds."
          },
          "amount": {
            "type": "string",
            "pattern": "^\\d{1,12}(\\.\\d{1,2})?$",
            "example": "10.00",
            "description": "US dollars, at most 2 decimals, at least 1.00 (at most the escrow's maxOrderAmount)."
          },
          "xUserId": {
            "type": "string",
            "pattern": "^\\d{1,20}$",
            "description": "The recipient's numeric X user id (a string: X ids exceed 2^53). Required unless `handle` is a nett user's.",
            "example": "1790000000000000001"
          },
          "handle": {
            "type": "string",
            "pattern": "^@?[A-Za-z0-9_]{1,15}$",
            "description": "The recipient's X handle (the @ is optional): resolved through nett users only, honouring their discoverability opt-out; checked against xUserId when both are given.",
            "example": "alice"
          },
          "maxFee": {
            "type": "string",
            "pattern": "^\\d{1,12}(\\.\\d{1,2})?$",
            "example": "0.10",
            "description": "Most you pay on top of amount (<= amount). Default: the quote's suggestedMaxFee."
          },
          "deadline": {
            "oneOf": [
              {
                "type": "integer",
                "description": "Unix seconds."
              },
              {
                "type": "string",
                "pattern": "^\\d{1,12}$"
              },
              {
                "type": "string",
                "format": "date-time"
              }
            ],
            "description": "After it the order can no longer be taken and becomes refundable: 10 minutes to 30 days from now (chain time). Default +24 h."
          }
        }
      },
      "Call": {
        "type": "object",
        "required": [
          "to",
          "data",
          "value",
          "description"
        ],
        "properties": {
          "to": {
            "type": "string",
            "pattern": "^0x[0-9a-fA-F]{40}$",
            "example": "0x70085048eCa377619e9584605e5C30868a7890E6"
          },
          "data": {
            "type": "string",
            "pattern": "^0x[0-9a-fA-F]*$"
          },
          "value": {
            "type": "string",
            "const": "0"
          },
          "description": {
            "type": "string"
          }
        }
      },
      "CallsResponse": {
        "type": "object",
        "required": [
          "calls"
        ],
        "properties": {
          "calls": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Call"
            }
          }
        }
      },
      "Approve": {
        "type": "object",
        "required": [
          "to",
          "data",
          "amountMicros",
          "spender",
          "currentAllowanceMicros",
          "needed"
        ],
        "properties": {
          "to": {
            "type": "string",
            "pattern": "^0x[0-9a-fA-F]{40}$",
            "example": "0x70085048eCa377619e9584605e5C30868a7890E6",
            "description": "USDG."
          },
          "data": {
            "type": "string",
            "pattern": "^0x[0-9a-fA-F]*$",
            "description": "approve(spender, amountMicros)."
          },
          "amountMicros": {
            "type": "string",
            "pattern": "^\\d+$",
            "example": "10100000",
            "description": "amount + maxFee of every payout of this app still awaiting a signature from this wallet."
          },
          "spender": {
            "type": "string",
            "pattern": "^0x[0-9a-fA-F]{40}$",
            "example": "0x70085048eCa377619e9584605e5C30868a7890E6",
            "description": "The escrow."
          },
          "currentAllowanceMicros": {
            "type": "string",
            "pattern": "^\\d+$",
            "example": "0"
          },
          "needed": {
            "type": "boolean",
            "description": "currentAllowanceMicros < amountMicros: send `approve` first."
          }
        }
      },
      "CreatePayoutsResponse": {
        "type": "object",
        "required": [
          "payouts",
          "approve"
        ],
        "properties": {
          "payouts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Payout"
            }
          },
          "approve": {
            "$ref": "#/components/schemas/Approve"
          }
        }
      },
      "TimelineEntry": {
        "type": "object",
        "required": [
          "type",
          "at",
          "txHash",
          "block"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "created",
              "locked",
              "pending_recipient",
              "claimed",
              "challenged",
              "reopened",
              "settled",
              "refunded",
              "cancelled"
            ]
          },
          "at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Block time (estimated for blocks the index did not fetch)."
          },
          "txHash": {
            "type": "string",
            "pattern": "^0x[0-9a-fA-F]{64}$"
          },
          "block": {
            "type": "integer"
          }
        }
      },
      "Payout": {
        "type": "object",
        "required": [
          "externalId",
          "status",
          "orderId",
          "ref",
          "from",
          "xUserId",
          "handle",
          "amount",
          "amountMicros",
          "maxFee",
          "maxFeeMicros",
          "deadline",
          "provider",
          "fee",
          "feeMicros",
          "feeRefund",
          "feeRefundMicros",
          "receiptUrl",
          "createdAt",
          "timeline"
        ],
        "properties": {
          "externalId": {
            "$ref": "#/components/schemas/ExternalId"
          },
          "status": {
            "$ref": "#/components/schemas/PayoutStatus"
          },
          "orderId": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^\\d+$",
            "description": "The escrow order (decimal string)."
          },
          "ref": {
            "type": "string",
            "pattern": "^0x[0-9a-f]{64}$",
            "description": "keccak256(abi.encodePacked(\"nett:v1:\", appId, \":\", externalId)), passed to createOrder."
          },
          "from": {
            "type": "string",
            "pattern": "^0x[0-9a-fA-F]{40}$",
            "example": "0x70085048eCa377619e9584605e5C30868a7890E6"
          },
          "xUserId": {
            "type": "string",
            "pattern": "^\\d{1,20}$"
          },
          "handle": {
            "type": [
              "string",
              "null"
            ],
            "description": "The X handle sent on chain (canonical case when it is a nett user's); null when none was given."
          },
          "amount": {
            "type": "string",
            "pattern": "^-?\\d+\\.\\d{2,6}$",
            "example": "10.00"
          },
          "amountMicros": {
            "type": "string",
            "pattern": "^\\d+$",
            "example": "10000000"
          },
          "maxFee": {
            "type": "string",
            "pattern": "^-?\\d+\\.\\d{2,6}$",
            "example": "0.10"
          },
          "maxFeeMicros": {
            "type": "string",
            "pattern": "^\\d+$",
            "example": "100000"
          },
          "deadline": {
            "type": "string",
            "format": "date-time"
          },
          "provider": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^0x[0-9a-fA-F]{40}$",
            "example": "0x70085048eCa377619e9584605e5C30868a7890E6",
            "description": "The provider (filler) holding or having filled the order."
          },
          "fee": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^-?\\d+\\.\\d{2,6}$",
            "example": "0.03",
            "description": "The provider's fee: locked at lock time, paid at the fill."
          },
          "feeMicros": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^\\d+$",
            "example": "30000"
          },
          "feeRefund": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^-?\\d+\\.\\d{2,6}$",
            "example": "0.07",
            "description": "maxFee - fee, credited back to the payer at the fill."
          },
          "feeRefundMicros": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^\\d+$",
            "example": "70000"
          },
          "receiptUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "example": "https://www.usenett.app/r.html?id=NT-12",
            "description": "The order's receipt. null without an order, or for a payout made for a previous escrow deployment."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "calls": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Call"
            },
            "description": "Only while awaiting_signature: createOrder(payeeXUserId, handle, amount, maxFee, deadline, false, ref) to the escrow, sent from `from` (after `approve` when needed). Never for a payout made for a previous escrow deployment (after a redeploy it cannot be sent again: create a new payout)."
          },
          "timeline": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TimelineEntry"
            }
          }
        }
      },
      "IgnoredOrder": {
        "type": "object",
        "required": [
          "orderId",
          "externalId",
          "reason"
        ],
        "properties": {
          "orderId": {
            "type": "string"
          },
          "externalId": {
            "type": [
              "string",
              "null"
            ]
          },
          "reason": {
            "type": "string",
            "enum": [
              "unknown_ref",
              "params_mismatch",
              "duplicate"
            ]
          }
        }
      },
      "Quote": {
        "type": "object",
        "required": [
          "amount",
          "amountMicros",
          "providers",
          "suggestedMaxFee",
          "suggestedMaxFeeMicros",
          "deadline",
          "contract"
        ],
        "properties": {
          "amount": {
            "type": "string",
            "pattern": "^-?\\d+\\.\\d{2,6}$",
            "example": "10.00"
          },
          "amountMicros": {
            "type": "string",
            "pattern": "^\\d+$",
            "example": "10000000"
          },
          "providers": {
            "type": "object",
            "required": [
              "active",
              "feeBps"
            ],
            "properties": {
              "active": {
                "type": "integer",
                "minimum": 0
              },
              "feeBps": {
                "type": "object",
                "required": [
                  "min",
                  "median",
                  "max"
                ],
                "properties": {
                  "min": {
                    "type": [
                      "integer",
                      "null"
                    ]
                  },
                  "median": {
                    "type": [
                      "integer",
                      "null"
                    ]
                  },
                  "max": {
                    "type": [
                      "integer",
                      "null"
                    ]
                  }
                }
              }
            }
          },
          "suggestedMaxFee": {
            "type": "string",
            "pattern": "^-?\\d+\\.\\d{2,6}$",
            "example": "0.10"
          },
          "suggestedMaxFeeMicros": {
            "type": "string",
            "pattern": "^\\d+$",
            "example": "100000"
          },
          "deadline": {
            "type": "object",
            "required": [
              "min",
              "max",
              "default"
            ],
            "properties": {
              "min": {
                "const": "+10m"
              },
              "max": {
                "const": "+30d"
              },
              "default": {
                "const": "+24h"
              }
            }
          },
          "contract": {
            "type": "object",
            "required": [
              "chainId",
              "escrow",
              "usdg",
              "decimals"
            ],
            "properties": {
              "chainId": {
                "const": 4663
              },
              "escrow": {
                "type": "string",
                "pattern": "^0x[0-9a-fA-F]{40}$",
                "example": "0x70085048eCa377619e9584605e5C30868a7890E6"
              },
              "usdg": {
                "type": "string",
                "pattern": "^0x[0-9a-fA-F]{40}$",
                "example": "0x70085048eCa377619e9584605e5C30868a7890E6"
              },
              "decimals": {
                "const": 6
              }
            },
            "description": "The only contracts a call may target: check them before signing."
          }
        }
      },
      "PayoutEvent": {
        "type": "object",
        "required": [
          "id",
          "type",
          "createdAt",
          "data"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^evt_[0-9a-f]{16}$",
            "description": "Stable across retries: deduplicate on it."
          },
          "type": {
            "type": "string",
            "enum": [
              "payout.created",
              "payout.locked",
              "payout.pending_recipient",
              "payout.reopened",
              "payout.settled",
              "payout.refunded",
              "payout.cancelled"
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "data": {
            "type": "object",
            "required": [
              "payout"
            ],
            "properties": {
              "payout": {
                "$ref": "#/components/schemas/Payout"
              }
            }
          }
        }
      },
      "PingEvent": {
        "type": "object",
        "required": [
          "id",
          "type",
          "createdAt",
          "data"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^evt_[0-9a-f]{16}$"
          },
          "type": {
            "const": "ping"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "data": {
            "type": "object",
            "required": [
              "appId"
            ],
            "properties": {
              "appId": {
                "type": "string"
              }
            }
          }
        }
      },
      "DispatchSummary": {
        "type": "object",
        "required": [
          "ok",
          "trigger",
          "skipped",
          "events",
          "enqueued",
          "attempted",
          "succeeded",
          "failed",
          "dead",
          "pending",
          "nextDueAt",
          "cursor",
          "errors",
          "ms"
        ],
        "properties": {
          "ok": {
            "const": true
          },
          "trigger": {
            "type": "string"
          },
          "skipped": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              null,
              "idle",
              "nothing_due",
              "leased",
              "running",
              "apps_not_configured"
            ]
          },
          "events": {
            "type": "integer"
          },
          "enqueued": {
            "type": "integer"
          },
          "attempted": {
            "type": "integer"
          },
          "succeeded": {
            "type": "integer"
          },
          "failed": {
            "type": "integer"
          },
          "dead": {
            "type": "integer"
          },
          "pending": {
            "type": "integer",
            "description": "Deliveries due and not sent in this run (time budget)."
          },
          "nextDueAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "cursor": {
            "type": [
              "string",
              "null"
            ],
            "description": "Last block processed."
          },
          "errors": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "ms": {
            "type": "integer"
          }
        }
      }
    }
  }
}
