{
  "openapi": "3.1.0",
  "info": {
    "title": "Nasfam Business API",
    "version": "1.0.0-draft.10",
    "summary": "Build with Nasfam Business: order digital products from a prefunded balance, and follow every order to its end.",
    "description": "DRAFT contract. Sandbox only in Phase 1; no live provider availability is claimed.\nEvery operation that moves money (`x-nb-moves-money: true`) requires an Idempotency-Key, bound permanently.\nThe balance is USD, in Sandbox and Live. Money amounts are integers in cents; exact USD figures are integer micro-dollar strings.\nGRAM (an organisation that pays with GRAM, ledger currency TON): its quotes and orders are priced in USD from the server's\nprice book (`amount`, USD cents) and charged as GRAM (`settlement`); every GRAM amount is an integer nanogram string\n(1 GRAM = 1,000,000,000 nanogram), rounded up. `GET /v1/rates` and `GET /v1/prices` are what it is quoted from.\nDisplay currencies (draft.6, display only; USD unless a member chooses another). A `display` object is an indicative equivalent, never\na balance, price, quote, charge or settlement, and choosing a display currency changes no other field.\nUSD (draft.7): an organisation that spends USD (`spending_currency`) holds USD credits in micro-dollars\n(`*_micros`, 1 USD = 1,000,000, integer strings). A deposit converts when it is credited: GRAM at the verified GRAM/USD rate\nless the deposit spread. With no verified rate\na deposit is held in its own asset, never credited at a guess. Quotes and orders charge USD.\nNot served yet: direct GRAM orders (a GRAM order is made from a quote), and\nGRAM in the balance statement (`/v1/balance/transactions` lists USD movements).\nRequests are strict: unknown request fields are rejected.\nFree-text request strings (metadata, filters, descriptions) never contain U+0000 or an unpaired surrogate, and a date-time is from year 0001 with an offset within 15:59: values outside what the store holds are refused 400 `invalid_request`, never accepted.\nResponses are extensible: integrations must ignore unknown response fields, enum values and event types.\nOrder events are ordered by the order's monotonic `version`, not by timestamps.\nQuickstart (draft.10): `POST /v1/orders` with `{\"product\": \"telegram_stars\", \"username\": \"@customer\", \"quantity\": 100}` (or `\"telegram_premium\"` with `months`) and an Idempotency-Key is a whole order. The server checks the recipient, prices it from the same price book a quote uses, and holds the funds, all in one step; `max_amount` is an optional ceiling. `GET /v1/recipients/lookup?username=&product=` is an optional check beforehand; an order never needs anything it returns. Both are on in the sandbox and in Live; the quote flow is unchanged.\nLook a recipient up before quoting (`POST /v1/recipient-lookups`): it returns the account the provider found at the username (display name and photo as returned, null where not) for your customer to confirm, and the quote that cites it (`recipient_lookup`) is refused if it no longer matches. \"Found\" means the provider found an account at that username; nothing here verifies who a Telegram account belongs to.\nRate limits are listed in `x-nb-rate-limits` and reported in the RateLimit-Policy and RateLimit headers of draft-ietf-httpapi-ratelimit-headers-11 (an Internet-Draft, not yet an RFC); a 429 carries Retry-After.\n"
  },
  "servers": [
    {
      "url": "https://sandbox-api.nasfampay.com/v1",
      "description": "Sandbox (nbk_test_ keys only)"
    },
    {
      "url": "https://api.nasfampay.com/v1",
      "description": "Production (nbk_live_ keys only)"
    }
  ],
  "x-nb-sandbox-scenarios": {
    "description": "Sandbox host only. A telegram_username in the reserved nasfam_test_ namespace chooses what the simulated provider does, through the real ledger and order states; nothing else in a request (amount, header, key, reference) changes behaviour, and every other request is answered by the API's ordinary rules, as in Live. Each name works for telegram_stars and telegram_premium (with months 3, 6 or 12, which the simulated provider requires, as the real one does). Live refuses every nasfam_test_ recipient, in any letter case: 422 recipient_not_eligible on /telegram_username. The scenarios a request or a webhook receiver chooses, and the timings: docs/api/SANDBOX_SCENARIOS.md.\n",
    "recipients": [
      {
        "telegram_username": "nasfam_test_ok",
        "summary": "Succeeds. Any ordinary username behaves the same.",
        "order": [
          {
            "status": "processing"
          },
          {
            "status": "succeeded"
          }
        ],
        "events": [
          "order.accepted",
          "order.processing",
          "order.succeeded"
        ],
        "balance_transactions": [
          "order_reserve",
          "order_capture"
        ]
      },
      {
        "telegram_username": "nasfam_test_slow",
        "summary": "Processing for about 2 minutes, then succeeds.",
        "order": [
          {
            "status": "processing"
          },
          {
            "status": "succeeded"
          }
        ],
        "events": [
          "order.accepted",
          "order.processing",
          "order.succeeded"
        ],
        "balance_transactions": [
          "order_reserve",
          "order_capture"
        ]
      },
      {
        "telegram_username": "nasfam_test_slow_rejected",
        "summary": "Processing for about 2 minutes, then a verified failure; the hold is released once.",
        "order": [
          {
            "status": "processing"
          },
          {
            "status": "failed",
            "status_reason": "definitive_rejection"
          }
        ],
        "events": [
          "order.accepted",
          "order.processing",
          "order.failed",
          "order.refunded"
        ],
        "balance_transactions": [
          "order_reserve",
          "order_release"
        ]
      },
      {
        "telegram_username": "nasfam_test_rejected",
        "summary": "A verified failure at once; the hold is released once.",
        "order": [
          {
            "status": "processing"
          },
          {
            "status": "failed",
            "status_reason": "definitive_rejection"
          }
        ],
        "events": [
          "order.accepted",
          "order.processing",
          "order.failed",
          "order.refunded"
        ],
        "balance_transactions": [
          "order_reserve",
          "order_release"
        ]
      },
      {
        "telegram_username": "nasfam_test_lost_ack",
        "summary": "The provider's answer is lost; a lookup finds the delivery, which is captured once. Never sent twice.",
        "order": [
          {
            "status": "processing"
          },
          {
            "status": "succeeded"
          }
        ],
        "events": [
          "order.accepted",
          "order.processing",
          "order.succeeded"
        ],
        "balance_transactions": [
          "order_reserve",
          "order_capture"
        ]
      },
      {
        "telegram_username": "nasfam_test_timeout",
        "summary": "The request never reaches the provider (UNKNOWN). Under review after 30 minutes, money held until two staff decide.",
        "order": [
          {
            "status": "processing"
          },
          {
            "status": "under_review",
            "status_reason": "outcome_unconfirmed"
          }
        ],
        "events": [
          "order.accepted",
          "order.processing",
          "order.under_review"
        ],
        "balance_transactions": [
          "order_reserve"
        ]
      },
      {
        "telegram_username": "nasfam_test_unknown",
        "summary": "Under review after 30 minutes, then a late success at about 35 minutes, captured once.",
        "order": [
          {
            "status": "processing"
          },
          {
            "status": "under_review",
            "status_reason": "outcome_unconfirmed"
          },
          {
            "status": "succeeded"
          }
        ],
        "events": [
          "order.accepted",
          "order.processing",
          "order.under_review",
          "order.succeeded"
        ],
        "balance_transactions": [
          "order_reserve",
          "order_capture"
        ]
      },
      {
        "telegram_username": "nasfam_test_conflict",
        "summary": "Every provider answer names another recipient. Under review at once, money held until two staff decide.",
        "order": [
          {
            "status": "processing"
          },
          {
            "status": "under_review",
            "status_reason": "provider_conflict"
          }
        ],
        "events": [
          "order.accepted",
          "order.processing",
          "order.under_review"
        ],
        "balance_transactions": [
          "order_reserve"
        ]
      },
      {
        "telegram_username": "nasfam_test_missing",
        "summary": "The recipient check finds nobody. The quote, or a direct order, is refused and nothing is reserved.",
        "problem": {
          "status": 422,
          "code": "recipient_not_found"
        }
      }
    ],
    "lookups": {
      "description": "What POST /v1/recipient-lookups answers for each sandbox name, and what a quote citing the lookup then does. Every other username is found, with display_name \"Sandbox user @<username>\" and no photo. A quote made without a lookup treats these names as ordinary recipients. Live refuses every nasfam_test_ lookup: 422 recipient_not_eligible.\n",
      "names": [
        {
          "telegram_username": "nasfam_test_ok",
          "summary": "Found, without a photo, as any ordinary username.",
          "lookup": {
            "status": 201
          }
        },
        {
          "telegram_username": "nasfam_test_photo",
          "summary": "Found, with a photo_url.",
          "lookup": {
            "status": 201,
            "photo": true
          }
        },
        {
          "telegram_username": "nasfam_test_missing",
          "summary": "Nobody has this username.",
          "lookup": {
            "status": 422,
            "code": "recipient_not_found"
          }
        },
        {
          "telegram_username": "nasfam_test_lookup_timeout",
          "summary": "The provider does not answer in time. Never reported as not found.",
          "lookup": {
            "status": 503,
            "code": "provider_unavailable",
            "retry_after": 2
          }
        },
        {
          "telegram_username": "nasfam_test_lookup_unavailable",
          "summary": "The provider fails (a 5xx or an unreadable answer). Never reported as not found.",
          "lookup": {
            "status": 503,
            "code": "provider_unavailable",
            "retry_after": 2
          }
        },
        {
          "telegram_username": "nasfam_test_lookup_rate_limited",
          "summary": "The provider throttles Nasfam (its 429). Retry after Retry-After; your own limit is 429 rate_limited.",
          "lookup": {
            "status": 503,
            "code": "provider_unavailable",
            "retry_after": 30
          }
        },
        {
          "telegram_username": "nasfam_test_lookup_expired",
          "summary": "Found, but already expired. A quote citing it is refused.",
          "lookup": {
            "status": 201
          },
          "quote": {
            "status": 409,
            "code": "lookup_expired"
          }
        },
        {
          "telegram_username": "nasfam_test_renamed",
          "summary": "Found; the account at the username changes before the quote, as a username released and taken by someone else.",
          "lookup": {
            "status": 201
          },
          "quote": {
            "status": 409,
            "code": "recipient_mismatch"
          }
        }
      ]
    }
  },
  "x-nb-rate-limits": {
    "description": "The request limits of this API, one token bucket each: a bucket holds `quota` requests (the burst) and refills from empty to full over `window_seconds`, so its sustained rate is quota / window_seconds a second; a bucket whose window is 86400 is a daily allowance. `scope` says whose bucket it is: `key`, each API key its own; `org`, one shared by every key and dashboard member of the organisation. A request draws one token from each bucket its operation lists in `applies_to`, all or none; createOrder draws the quote buckets only for a direct order (one without `quote_id`), which makes its own quote, so every order counts against `quotes_daily` once. Past a bucket, `429 rate_limited` with Retry-After. Every response names the buckets it drew on in RateLimit-Policy with that organisation's own figures: an organisation's `quotes_daily` or `lookups_daily` can be set higher (or lower) for that organisation alone, by two Nasfam staff; every other figure is the same for everyone. Admission from capacity is separate (`429 queue_limit`, `503 capacity_exhausted`). These figures are the database's (ops.rate_policies), checked against it by test RL-P01.\n",
    "buckets": [
      {
        "bucket": "orders",
        "scope": "key",
        "quota": 20,
        "window_seconds": 4,
        "applies_to": [
          "createOrder",
          "createSandboxFunding",
          "createSandboxGramDeposit",
          "createSandboxDeposit",
          "createSandboxTestRun"
        ]
      },
      {
        "bucket": "quotes",
        "scope": "org",
        "quota": 5,
        "window_seconds": 5,
        "applies_to": [
          "createQuote",
          "createOrder"
        ]
      },
      {
        "bucket": "quotes_daily",
        "scope": "org",
        "quota": 20000,
        "window_seconds": 86400,
        "applies_to": [
          "createQuote",
          "createOrder"
        ]
      },
      {
        "bucket": "reads",
        "scope": "key",
        "quota": 25,
        "window_seconds": 2,
        "applies_to": [
          "listProducts",
          "getRates",
          "listPrices",
          "listOrders",
          "getOrder",
          "getBalance",
          "listBalanceTransactions",
          "listFundingAccounts",
          "listFundings",
          "getLimits",
          "createStatement",
          "listStatements",
          "getStatement",
          "getDepositAddress",
          "listGramDeposits",
          "listEvents",
          "getEvent",
          "getAccount",
          "listWebhookEndpoints",
          "getWebhookEndpoint",
          "listWebhookDeliveries",
          "listSandboxTestRuns",
          "getSandboxTestRun"
        ]
      },
      {
        "bucket": "webhooks",
        "scope": "key",
        "quota": 5,
        "window_seconds": 5,
        "applies_to": [
          "createWebhookEndpoint",
          "updateWebhookEndpoint",
          "deleteWebhookEndpoint",
          "rotateWebhookSecret",
          "replayWebhookDelivery",
          "sendWebhookTestEvent"
        ]
      },
      {
        "bucket": "lookups",
        "scope": "key",
        "quota": 10,
        "window_seconds": 5,
        "applies_to": [
          "createRecipientLookup",
          "lookupRecipient"
        ]
      },
      {
        "bucket": "lookups_org",
        "scope": "org",
        "quota": 20,
        "window_seconds": 10,
        "applies_to": [
          "createRecipientLookup",
          "lookupRecipient"
        ]
      },
      {
        "bucket": "lookups_daily",
        "scope": "org",
        "quota": 20000,
        "window_seconds": 86400,
        "applies_to": [
          "createRecipientLookup",
          "lookupRecipient"
        ]
      }
    ]
  },
  "x-nb-problem-codes": {
    "description": "Every problem code with its HTTP status and its category (Problem.category). One rule overrides a code's category, internal_error on an operation marked x-nb-moves-money is unknown_outcome. The public API never answers the dashboard's session and member codes.",
    "codes": {
      "invalid_request": {
        "status": 400,
        "category": "validation"
      },
      "organisation_required": {
        "status": 400,
        "category": "authentication"
      },
      "unknown_field": {
        "status": 400,
        "category": "validation"
      },
      "idempotency_key_required": {
        "status": 400,
        "category": "validation"
      },
      "support_sensitive": {
        "status": 400,
        "category": "validation"
      },
      "scope_above_role": {
        "status": 400,
        "category": "authorisation"
      },
      "invalid_api_key": {
        "status": 401,
        "category": "authentication"
      },
      "key_expired": {
        "status": 401,
        "category": "authentication"
      },
      "key_environment_mismatch": {
        "status": 401,
        "category": "authentication"
      },
      "session_required": {
        "status": 401,
        "category": "authentication"
      },
      "invalid_id_token": {
        "status": 401,
        "category": "authentication"
      },
      "reauthentication_required": {
        "status": 401,
        "category": "authentication"
      },
      "insufficient_funds": {
        "status": 402,
        "category": "balance"
      },
      "insufficient_scope": {
        "status": 403,
        "category": "authorisation"
      },
      "product_not_permitted": {
        "status": 403,
        "category": "authorisation"
      },
      "ip_not_allowed": {
        "status": 403,
        "category": "authorisation"
      },
      "account_restricted": {
        "status": 403,
        "category": "authorisation"
      },
      "browser_request_refused": {
        "status": 403,
        "category": "authentication"
      },
      "csrf_invalid": {
        "status": 403,
        "category": "authentication"
      },
      "origin_refused": {
        "status": 403,
        "category": "authentication"
      },
      "insufficient_role": {
        "status": 403,
        "category": "authorisation"
      },
      "not_a_member": {
        "status": 403,
        "category": "authorisation"
      },
      "email_unverified": {
        "status": 403,
        "category": "authentication"
      },
      "second_factor_required": {
        "status": 403,
        "category": "authentication"
      },
      "sandbox_proof_invalid": {
        "status": 403,
        "category": "authorisation"
      },
      "approver_identity_unverified": {
        "status": 403,
        "category": "authorisation"
      },
      "recovery_refused": {
        "status": 403,
        "category": "authentication"
      },
      "recovery_staff_required": {
        "status": 403,
        "category": "authentication"
      },
      "not_found": {
        "status": 404,
        "category": "validation"
      },
      "support_case_not_found": {
        "status": 404,
        "category": "validation"
      },
      "last_owner": {
        "status": 409,
        "category": "validation"
      },
      "quote_expired": {
        "status": 409,
        "category": "validation"
      },
      "quote_already_used": {
        "status": 409,
        "category": "validation"
      },
      "lookup_expired": {
        "status": 409,
        "category": "validation"
      },
      "recipient_mismatch": {
        "status": 409,
        "category": "validation"
      },
      "price_changed": {
        "status": 409,
        "category": "validation"
      },
      "duplicate_reference": {
        "status": 409,
        "category": "validation"
      },
      "idempotency_in_progress": {
        "status": 409,
        "category": "unknown_outcome"
      },
      "endpoint_limit": {
        "status": 409,
        "category": "webhook"
      },
      "key_limit_reached": {
        "status": 409,
        "category": "validation"
      },
      "workspace_limit_reached": {
        "status": 409,
        "category": "validation"
      },
      "invitation_limit_reached": {
        "status": 409,
        "category": "validation"
      },
      "invitation_unavailable": {
        "status": 409,
        "category": "validation"
      },
      "already_a_member": {
        "status": 409,
        "category": "validation"
      },
      "activation_not_available": {
        "status": 409,
        "category": "authorisation"
      },
      "sandbox_test_incomplete": {
        "status": 409,
        "category": "validation"
      },
      "live_workspace_exists": {
        "status": 409,
        "category": "validation"
      },
      "sandbox_workspace_linked": {
        "status": 409,
        "category": "validation"
      },
      "key_not_active": {
        "status": 409,
        "category": "validation"
      },
      "key_already_rotated": {
        "status": 409,
        "category": "validation"
      },
      "stale_state": {
        "status": 409,
        "category": "validation"
      },
      "case_closed": {
        "status": 409,
        "category": "validation"
      },
      "payload_too_large": {
        "status": 413,
        "category": "validation"
      },
      "unsupported_media_type": {
        "status": 415,
        "category": "validation"
      },
      "idempotency_key_reused": {
        "status": 422,
        "category": "validation"
      },
      "recipient_not_found": {
        "status": 422,
        "category": "validation"
      },
      "recipient_not_eligible": {
        "status": 422,
        "category": "validation"
      },
      "recipient_lookup_required": {
        "status": 422,
        "category": "validation"
      },
      "product_unavailable": {
        "status": 422,
        "category": "authorisation"
      },
      "order_limit_exceeded": {
        "status": 422,
        "category": "validation"
      },
      "spending_limit_reached": {
        "status": 422,
        "category": "validation"
      },
      "version_conflict": {
        "status": 409,
        "category": "validation"
      },
      "statement_not_ready": {
        "status": 409,
        "category": "validation"
      },
      "webhook_url_refused": {
        "status": 422,
        "category": "webhook"
      },
      "rate_limited": {
        "status": 429,
        "category": "rate_limit"
      },
      "queue_limit": {
        "status": 429,
        "category": "rate_limit"
      },
      "support_limited": {
        "status": 429,
        "category": "rate_limit"
      },
      "internal_error": {
        "status": 500,
        "category": "internal"
      },
      "capacity_exhausted": {
        "status": 503,
        "category": "provider"
      },
      "pricing_unavailable": {
        "status": 503,
        "category": "provider"
      },
      "provider_unavailable": {
        "status": 503,
        "category": "provider"
      },
      "service_unavailable": {
        "status": 503,
        "category": "internal"
      }
    }
  },
  "security": [
    {
      "apiKey": []
    }
  ],
  "tags": [
    {
      "name": "Products"
    },
    {
      "name": "Recipients"
    },
    {
      "name": "Quotes"
    },
    {
      "name": "Prices"
    },
    {
      "name": "Orders"
    },
    {
      "name": "Balance"
    },
    {
      "name": "Funding"
    },
    {
      "name": "Statements",
      "description": "Reconciled account statements over whole local days (statements:read)."
    },
    {
      "name": "Limits"
    },
    {
      "name": "Events"
    },
    {
      "name": "Webhooks"
    },
    {
      "name": "Account"
    },
    {
      "name": "Sandbox"
    }
  ],
  "paths": {
    "/products": {
      "get": {
        "tags": [
          "Products"
        ],
        "operationId": "listProducts",
        "summary": "List products",
        "responses": {
          "200": {
            "description": "Products",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ListMeta"
                    },
                    {
                      "type": "object",
                      "required": [
                        "data"
                      ],
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Product"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/prices": {
      "get": {
        "tags": [
          "Prices"
        ],
        "operationId": "listPrices",
        "summary": "The USD price book in effect, with indicative GRAM figures",
        "description": "The packages GRAM is sold in, each with its USD price. `indicative_nanogram` is the package at the newest good GRAM/USD\nrate, labelled indicative: what an order charges is its quote's `settlement`. `display_currency` adds an estimated price\nin that currency at a display rate, never charged. A database with no book of its own answers `available: false`.\n`price_basis` says how these prices are set and when they can change; a quote carries its own.\n",
        "parameters": [
          {
            "name": "display_currency",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "EUR",
                "GBP"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The price book in effect",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PriceList"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/rates": {
      "get": {
        "tags": [
          "Prices"
        ],
        "operationId": "getRates",
        "summary": "The GRAM/USD reference rate GRAM quotes are priced at, and display rates",
        "description": "`gram_usd` is the newest judgement of the GRAM/USD reference rate, as an exact fraction of USD micros per GRAM, with its\nsource time. A quote is priced only while `quotable` is true (before `valid_until`); otherwise quotes are refused\n`503 pricing_unavailable`. `display` rates are indicative and never charged. Each display rate is judged from two\nindependent sources (draft.6): `shown` is true only when it is fresh and they agree within `tolerance_bps`, and\n`judged` is then the figure to show, with its source and label. A page shows no figure when `shown` is false.\n",
        "responses": {
          "200": {
            "description": "Rates",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Rates"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/recipient-lookups": {
      "post": {
        "tags": [
          "Recipients"
        ],
        "operationId": "createRecipientLookup",
        "x-nb-moves-money": false,
        "summary": "Look up a Telegram recipient before quoting",
        "description": "Resolves a username to the account the provider found there: its display name and photo, exactly as returned (null where the provider returned none), for your customer to confirm before you quote. Read-only: it never charges, reserves, prices or delivers anything. Cite the lookup's `id` as `recipient_lookup` in `POST /v1/quotes`; it is valid until `expires_at` (10 minutes) and only for the same username, product and selection.\n`found: true` means the provider found an account at that username. It does not verify who the account belongs to: show the name and photo and let your customer confirm. A provider that cannot answer is `503 provider_unavailable` (retry after Retry-After), never `recipient_not_found`.\nDraws on the `lookups` (per key), `lookups_org` and `lookups_daily` (per organisation) buckets, not on the quote buckets. No Idempotency-Key: a repeated lookup is answered from the organisation's own recent answer for the same username, product and selection (found within 30 seconds, not found within 60) without asking the provider again.\nIn the sandbox the nasfam_test_ names in `x-nb-sandbox-scenarios.lookups` choose the answer. In Live every nasfam_test_ name is refused 422 recipient_not_eligible.\nWhen Nasfam turns real lookups on in the sandbox, any other username is looked up through the provider's read-only search (`lookup_source: provider`), within tighter limits: 20 per key or member every 10 minutes, 60 per organisation an hour and 300 a day (`429 rate_limited` with Retry-After); the quote and the order that follow stay synthetic. Otherwise the sandbox's simulator answers (`lookup_source: simulated`).\nCall it from your server: the secret key never goes to a browser or an app.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RecipientLookupRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "An account was found at the username",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RecipientLookup"
                }
              }
            }
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/recipients/lookup": {
      "get": {
        "tags": [
          "Recipients"
        ],
        "operationId": "lookupRecipient",
        "x-nb-moves-money": false,
        "summary": "Check a Telegram username before ordering (optional)",
        "description": "Only a username and a product: whether an account was found at the username and whether the provider refused it for the product. Optional: an order never needs it and never cites it, and it returns no id.\n`product` is asked because the provider's search is per product (Telegram Stars or Premium), and it can refuse an account for one and not the other. `found: true` means an account is at the username, nothing more: it never verifies who owns it, and no Premium status is returned because the provider reports none.\nA definitive answer is 200: `found: false` with `reason: recipient_not_found`, or `found: true` with `eligibility: refused` and `reason: recipient_not_eligible`. A provider that cannot answer is `503 provider_unavailable` with Retry-After, never `found: false`.\nDraws on the same `lookups`, `lookups_org` and `lookups_daily` buckets as `POST /v1/recipient-lookups`; a repeated question is answered from this organisation's own recent answer (found within 30 seconds, not found within 60) without asking the provider again. In the sandbox the `nasfam_test_` names of `x-nb-sandbox-scenarios.lookups` choose the answer; Live refuses every one, 422 `recipient_not_eligible`.\nOn in the sandbox and in Live. Call it from your server.\n",
        "parameters": [
          {
            "name": "username",
            "in": "query",
            "required": true,
            "description": "A username as your customer types it (`name`, `@name`, `t.me/name`); the answer carries it normalised.",
            "schema": {
              "$ref": "#/components/schemas/TelegramRecipientInput"
            }
          },
          {
            "name": "product",
            "in": "query",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/ProductInput"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The provider's answer for this username and product",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RecipientCheck"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/quotes": {
      "post": {
        "tags": [
          "Quotes"
        ],
        "operationId": "createQuote",
        "x-nb-moves-money": false,
        "summary": "Verify a recipient and lock a price for up to 60 seconds",
        "description": "Cite the recipient lookup your customer confirmed as `recipient_lookup` (recommended). The quote is then refused unless the lookup is this organisation's (`404 not_found` otherwise), unexpired (`409 lookup_expired`) and for the same username, product and selection, and the account the provider finds at the username now is the one the lookup found (`409 recipient_mismatch`). Without it the quote checks the recipient itself, as before. `recipient_lookup` is not part of the Idempotency-Key's request: a replay returns the first quote as it was made.\nIn the sandbox, nasfam_test_missing is refused 422 recipient_not_found and every other nasfam_test_ recipient chooses the order's outcome (x-nb-sandbox-scenarios). In Live every nasfam_test_ recipient is refused 422 recipient_not_eligible.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKeyOptional"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/QuoteRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A replay of an earlier request with the same Idempotency-Key: the quote it made, unchanged (it may have expired since). Nothing is priced again.",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "Idempotent-Replayed": {
                "schema": {
                  "type": "string",
                  "enum": [
                    "true"
                  ]
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Quote"
                }
              }
            }
          },
          "201": {
            "description": "Quote created",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Quote"
                }
              }
            }
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/orders": {
      "post": {
        "tags": [
          "Orders"
        ],
        "operationId": "createOrder",
        "x-nb-moves-money": true,
        "summary": "Create an order (funds are reserved before the response)",
        "description": "Order from a quote (`quote_id`), or directly (`product`, `telegram_username`, `max_amount`). A direct order makes its own quote, so it draws on the organisation's `quotes` and `quotes_daily` buckets as well as `orders`, a replay of it included.\nThe quickest order (draft.10, a USD organisation): `{\"product\": \"telegram_stars\", \"username\": \"@customer\", \"quantity\": 100}` or `{\"product\": \"telegram_premium\", \"username\": \"@customer\", \"months\": 3}`, with an Idempotency-Key. Nothing else is needed: no quote, no lookup, no id. In one step the server checks the recipient, prices the order from the same price book and functions a quote uses, checks your limits and available balance, and holds the exact amount. A price it cannot determine from fresh figures is `503 pricing_unavailable` and nothing is held. `max_amount` (optional, USD in cents) is a ceiling: an order that would cost more is refused `409 price_changed` at `/max_amount` and nothing is held. The order answered is the one `GET /v1/orders/{id}` returns; its `product` is the full product id (`telegram_stars`, `telegram_premium`) whichever name you sent. It draws on the `quotes` buckets as a direct order does.\nRetrying with the same Idempotency-Key and the same order (the same product, normalised username and selection, `max_amount`, `reference` and `metadata`) returns the first order (200, Idempotent-Replayed) and never holds or delivers twice; the same key with a different order is `422 idempotency_key_reused`. On in the sandbox and in Live, for an organisation that spends USD or GRAM; one still on its legacy currency orders from a quote. The recipient is resolved inside the order, so it needs no lookup even where Nasfam requires one for quotes.\nThe safe flow: look the recipient up (`POST /v1/recipient-lookups`), let your customer confirm, quote citing the lookup, then order with an `Idempotency-Key`. The order shows its lookup as `recipient_lookup`. A lookup past `expires_at` refuses the order with `409 lookup_expired` and nothing is held; look the recipient up again. A retry with the same key and body returns the first order, however old its lookup.\nIn the sandbox, the recipient chooses the outcome: each `nasfam_test_` recipient's statuses, events and balance transactions are listed in `x-nb-sandbox-scenarios`. In Live every `nasfam_test_` recipient is refused `422 recipient_not_eligible`.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKeyRequired"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/OrderFromQuote"
                  },
                  {
                    "$ref": "#/components/schemas/OrderDirect"
                  },
                  {
                    "$ref": "#/components/schemas/OrderStars"
                  },
                  {
                    "$ref": "#/components/schemas/OrderPremium"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Replay of an earlier request with the same Idempotency-Key. Returns the order's current state.",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "Idempotent-Replayed": {
                "schema": {
                  "type": "string",
                  "enum": [
                    "true"
                  ]
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Order"
                }
              }
            }
          },
          "202": {
            "description": "Accepted. Funds are held and delivery is in progress.",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Order"
                }
              }
            }
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      },
      "get": {
        "tags": [
          "Orders"
        ],
        "operationId": "listOrders",
        "summary": "List orders",
        "parameters": [
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/OrderStatus"
            }
          },
          {
            "name": "product",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/ProductId"
            }
          },
          {
            "name": "reference",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 64,
              "pattern": "^[^\\u0000\\uD800-\\uDFFF]*$"
            }
          },
          {
            "name": "telegram_username",
            "in": "query",
            "description": "Only orders for this recipient, matched exactly after the server normalises it as a quote does (`@name`, `t.me/name` and any letter case find `name`).",
            "schema": {
              "$ref": "#/components/schemas/TelegramRecipientInput"
            }
          },
          {
            "name": "created[gte]",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time",
              "pattern": "^(?!0000-).*(?:[Zz]|[+-](?:0[0-9]|1[0-5]):[0-5][0-9])$"
            }
          },
          {
            "name": "created[lt]",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time",
              "pattern": "^(?!0000-).*(?:[Zz]|[+-](?:0[0-9]|1[0-5]):[0-5][0-9])$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Orders, newest first",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ListMeta"
                    },
                    {
                      "type": "object",
                      "required": [
                        "data"
                      ],
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Order"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/orders/{id}": {
      "get": {
        "tags": [
          "Orders"
        ],
        "operationId": "getOrder",
        "summary": "Retrieve an order",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^ord_[0-9A-HJKMNP-TV-Z]{26}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The order",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Order"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/balance": {
      "get": {
        "tags": [
          "Balance"
        ],
        "operationId": "getBalance",
        "summary": "Available, held and pending-funding balances",
        "description": "The authoritative figures are the ledger's, each in its own currency, and are unchanged by anything about display.\n`display` adds an indicative equivalent of the available balance in the display currency (the workspace default for\nan API key, then the declared country's currency when served, then USD), with the rates, sources and time it was\ndrawn from. It shows a figure only when every rate used is fresh and two independent sources agree.\n",
        "responses": {
          "200": {
            "description": "Balance",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Balance"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/balance/transactions": {
      "get": {
        "tags": [
          "Balance"
        ],
        "operationId": "listBalanceTransactions",
        "summary": "Every movement on the balance",
        "parameters": [
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "$ref": "#/components/parameters/Cursor"
          }
        ],
        "responses": {
          "200": {
            "description": "Balance transactions, newest first",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ListMeta"
                    },
                    {
                      "type": "object",
                      "required": [
                        "data"
                      ],
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/BalanceTransaction"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/limits": {
      "get": {
        "tags": [
          "Limits"
        ],
        "operationId": "getLimits",
        "summary": "The platform's limits, the workspace's own spending limits and what they have used",
        "description": "Needs `limits:read`. The platform's limits are set by Nasfam and count Africa/Lagos days whatever the workspace zone. The\nworkspace's limits count commitments: an order reserves its charge when it is accepted and gives it back only when it is\nreleased (failed with evidence, or never submitted). `enforced` is true only for a blocking limit while enforcement is on,\nin a USD workspace. An order a limit refuses answers 422 `spending_limit_reached`. Amounts are micro-dollars\n(1 USD = 1,000,000) as integer strings.\n",
        "responses": {
          "200": {
            "description": "Limits",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Limits"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/statements": {
      "post": {
        "tags": [
          "Statements"
        ],
        "operationId": "createStatement",
        "x-nb-moves-money": false,
        "summary": "Request an account statement for whole local days",
        "description": "Needs `statements:read`. `from` and `to` are local dates in the workspace's finance zone, `to` excluded and at most the current day,\nat most 366 days. The server prepares the statement once the period is complete and reconciles it before any file exists:\nopening plus every movement must equal the closing recomputed from the ledger, or it fails with `reconciliation_failed`.\nCSV always, PDF only where the server offers it. The files are downloaded from the dashboard. Amounts are micro-dollars (1 USD = 1,000,000) as integer strings, and\nexact dollars to six decimals in the CSV. A retry with the same Idempotency-Key answers the same statement.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKeyRequired"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/StatementCreate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Replay of an earlier request with the same Idempotency-Key",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "Idempotent-Replayed": {
                "schema": {
                  "type": "string",
                  "enum": [
                    "true"
                  ]
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Statement"
                }
              }
            }
          },
          "202": {
            "description": "The statement, queued",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Statement"
                }
              }
            }
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      },
      "get": {
        "tags": [
          "Statements"
        ],
        "operationId": "listStatements",
        "summary": "The workspace's statements, newest first",
        "description": "Needs `statements:read`.",
        "parameters": [
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "$ref": "#/components/parameters/Cursor"
          }
        ],
        "responses": {
          "200": {
            "description": "Statements",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StatementList"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/statements/{id}": {
      "get": {
        "tags": [
          "Statements"
        ],
        "operationId": "getStatement",
        "summary": "One statement, its state and, once ready, its reconciled summary",
        "description": "Needs `statements:read`. Another workspace's statement is 404, as an unknown one.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^stm_[0-9A-HJKMNP-TV-Z]{26}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The statement",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Statement"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/fundings": {
      "get": {
        "tags": [
          "Funding"
        ],
        "operationId": "listFundings",
        "summary": "Incoming transfers and their state",
        "parameters": [
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "$ref": "#/components/parameters/Cursor"
          }
        ],
        "responses": {
          "200": {
            "description": "Fundings, newest first",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ListMeta"
                    },
                    {
                      "type": "object",
                      "required": [
                        "data"
                      ],
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Funding"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/funding/deposit-address": {
      "get": {
        "tags": [
          "Funding"
        ],
        "operationId": "getDepositAddress",
        "summary": "Your organisation's Gram (GRAM) deposit address on the TON network",
        "description": "One address per organisation, allocated on the first request and never changed. It is `preparing` until the server has recomputed it independently from the custody key and found it unused on chain, and only then shown, in its non-bounceable form (UQ on mainnet, 0Q on testnet). Send only native GRAM on TON: tokens, NFTs and other networks are not credited. A deposit is credited once the TON network has finalised it and two independent sources agree.\n",
        "responses": {
          "200": {
            "description": "The deposit address",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DepositAddress"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/funding/deposits": {
      "get": {
        "tags": [
          "Funding"
        ],
        "operationId": "listGramDeposits",
        "summary": "GRAM deposits to your address, and their state",
        "parameters": [
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "$ref": "#/components/parameters/Cursor"
          }
        ],
        "responses": {
          "200": {
            "description": "Deposits, newest first",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ListMeta"
                    },
                    {
                      "type": "object",
                      "required": [
                        "data"
                      ],
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Deposit"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/events": {
      "get": {
        "tags": [
          "Events"
        ],
        "operationId": "listEvents",
        "summary": "Event log (30-day retention)",
        "parameters": [
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "name": "type",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/EventType"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Events, newest first",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ListMeta"
                    },
                    {
                      "type": "object",
                      "required": [
                        "data"
                      ],
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Event"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/events/{id}": {
      "get": {
        "tags": [
          "Events"
        ],
        "operationId": "getEvent",
        "summary": "Retrieve an event",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^evt_[0-9A-HJKMNP-TV-Z]{26}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The event",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Event"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/webhook-endpoints": {
      "get": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "listWebhookEndpoints",
        "summary": "List webhook endpoints",
        "responses": {
          "200": {
            "description": "Endpoints",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ListMeta"
                    },
                    {
                      "type": "object",
                      "required": [
                        "data"
                      ],
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/WebhookEndpoint"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      },
      "post": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "createWebhookEndpoint",
        "x-nb-moves-money": false,
        "summary": "Create a webhook endpoint (the secret is returned once)",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKeyOptional"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookEndpointCreate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A replay of an earlier request with the same Idempotency-Key: the endpoint it made, as it is now, and no secret, which is shown in the 201 only. Nothing is created again.",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "Idempotent-Replayed": {
                "schema": {
                  "type": "string",
                  "enum": [
                    "true"
                  ]
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookEndpoint"
                }
              }
            }
          },
          "201": {
            "description": "Created",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookEndpointWithSecret"
                }
              }
            }
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/webhook-endpoints/{id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "pattern": "^whe_[0-9A-HJKMNP-TV-Z]{26}$"
          }
        }
      ],
      "get": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "getWebhookEndpoint",
        "responses": {
          "200": {
            "description": "Endpoint",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookEndpoint"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      },
      "patch": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "updateWebhookEndpoint",
        "x-nb-moves-money": false,
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookEndpointUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookEndpoint"
                }
              }
            }
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      },
      "delete": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "deleteWebhookEndpoint",
        "x-nb-moves-money": false,
        "responses": {
          "204": {
            "description": "Deleted",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/webhook-endpoints/{id}/rotate-secret": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "rotateWebhookSecret",
        "x-nb-moves-money": false,
        "summary": "Issue a new secret. Both secrets sign for 24 hours.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^whe_[0-9A-HJKMNP-TV-Z]{26}$"
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyOptional"
          }
        ],
        "responses": {
          "200": {
            "description": "Rotated: the new secret, in this response only. A replay of an earlier request with the same Idempotency-Key (Idempotent-Replayed: true) is the endpoint as it is now and no secret; nothing is rotated again.",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "Idempotent-Replayed": {
                "schema": {
                  "type": "string",
                  "enum": [
                    "true"
                  ]
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookEndpointRotation"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/webhook-endpoints/{id}/deliveries": {
      "get": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "listWebhookDeliveries",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^whe_[0-9A-HJKMNP-TV-Z]{26}$"
            }
          },
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "$ref": "#/components/parameters/Cursor"
          }
        ],
        "responses": {
          "200": {
            "description": "Delivery attempts, newest first",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ListMeta"
                    },
                    {
                      "type": "object",
                      "required": [
                        "data"
                      ],
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/WebhookDelivery"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/webhook-deliveries/{id}/replay": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "replayWebhookDelivery",
        "x-nb-moves-money": false,
        "summary": "Resend the same event (same webhook-id). Never creates a financial event.",
        "description": "Re-arms the same delivery: the same event and webhook-id, a new timestamp and signature, its attempts numbered on and\nits retry schedule started again. It never creates an event, an order or a balance movement. A delivery whose endpoint\nis disabled is `400 invalid_request` (nothing would be sent: enable the endpoint first), as a test event to it is; one of\nan event created more than 30 days ago is `400 invalid_request`, and an endpoint's deliveries are replayed at most 10 times in any hour\nand one delivery at most 3 times in any day (`429 rate_limited` with Retry-After). A delivery being attempted right\nnow is left to finish. Each replay is audited.\n",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^whd_[0-9A-HJKMNP-TV-Z]{26}$"
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyOptional"
          }
        ],
        "responses": {
          "200": {
            "description": "A replay of an earlier request with the same Idempotency-Key: the delivery, as it is now. Nothing is re-armed again.",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "Idempotent-Replayed": {
                "schema": {
                  "type": "string",
                  "enum": [
                    "true"
                  ]
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookDelivery"
                }
              }
            }
          },
          "202": {
            "description": "Replay scheduled",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookDelivery"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/webhook-endpoints/{id}/test": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "sendWebhookTestEvent",
        "x-nb-moves-money": false,
        "summary": "Send one test event of a type the endpoint subscribes to. It is marked and synthetic, and never a real order or funding.",
        "description": "The event is signed under the endpoint's secrets and delivered, retried and listed in its deliveries exactly as a real event is, so a receiver's signature verification is checked before a real order. Its envelope says `\"test\": true` and its id is an `evt_` ULID dated 1970-01-01 (`evt_0000000000...`), which no real event has. Its object is shaped as the event type's real object (the Order of an `order.*` event, the Funding of `funding.credited`) with the all-zero id (`ord_00000000000000000000000000`, `fnd_00000000000000000000000000`): fetching it is 404, so a receiver that fetches the object before releasing value releases nothing. `order.failed` carries `status_reason: provider_rejected` and `order.under_review` `outcome_unconfirmed`. It is not in the event log, reaches no other endpoint and creates no order, funding or balance movement. A type the endpoint does not subscribe to (`param: /type`), or a disabled endpoint, is `400 invalid_request`. An endpoint takes at most 20 test events in any hour; the next is `429 rate_limited` with Retry-After. Each request sends one test event: there is no Idempotency-Key.\n",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^whe_[0-9A-HJKMNP-TV-Z]{26}$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookTestEventCreate"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "The test event is made and its delivery scheduled",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookDelivery"
                }
              }
            }
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/account": {
      "get": {
        "tags": [
          "Account"
        ],
        "operationId": "getAccount",
        "responses": {
          "200": {
            "description": "The organisation behind this key",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Account"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/sandbox/funding/deposits": {
      "post": {
        "tags": [
          "Sandbox"
        ],
        "operationId": "createSandboxGramDeposit",
        "x-nb-moves-money": true,
        "summary": "Simulate a GRAM deposit to your address (sandbox host only; 404 in production)",
        "description": "Synthetic money, on no chain. The deposit is judged by the same rules as a real one (below the minimum it needs attention and is not credited), then booked by the same journal. A retry with the same Idempotency-Key returns the original deposit and credits nothing.",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKeyRequired"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "amount_nanogram"
                ],
                "properties": {
                  "amount_nanogram": {
                    "type": "string",
                    "pattern": "^[1-9][0-9]{0,12}$",
                    "description": "nanoGRAM: 1 to 1,000 GRAM (1000000000000) per simulated deposit"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Replay of an earlier request with the same Idempotency-Key. Nothing new is credited.",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "Idempotent-Replayed": {
                "schema": {
                  "type": "string",
                  "enum": [
                    "true"
                  ]
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GramDeposit"
                }
              }
            }
          },
          "201": {
            "description": "Simulated deposit, waiting for its booking",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GramDeposit"
                }
              }
            }
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/sandbox/deposits": {
      "post": {
        "tags": [
          "Sandbox"
        ],
        "operationId": "createSandboxDeposit",
        "x-nb-moves-money": true,
        "summary": "Simulate a GRAM deposit to your address (sandbox host only; 404 in production)",
        "description": "Synthetic money, on no chain. GRAM, judged by the same rules as a real deposit: below the minimum it needs attention and is not credited. It is then booked by the same journal as a real one. A retry with the same Idempotency-Key returns the original deposit and credits nothing.",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKeyRequired"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "additionalProperties": false,
                    "required": [
                      "asset",
                      "amount_nanogram"
                    ],
                    "properties": {
                      "asset": {
                        "type": "string",
                        "enum": [
                          "GRAM"
                        ]
                      },
                      "amount_nanogram": {
                        "type": "string",
                        "pattern": "^[1-9][0-9]{0,12}$",
                        "description": "nanoGRAM: 1 to 1,000 GRAM (1000000000000) per simulated deposit"
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Replay of an earlier request with the same Idempotency-Key. Nothing new is credited.",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "Idempotent-Replayed": {
                "schema": {
                  "type": "string",
                  "enum": [
                    "true"
                  ]
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Deposit"
                }
              }
            }
          },
          "201": {
            "description": "Simulated deposit, waiting for its booking",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Deposit"
                }
              }
            }
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/sandbox/test-runs": {
      "post": {
        "tags": [
          "Sandbox"
        ],
        "operationId": "createSandboxTestRun",
        "x-nb-moves-money": false,
        "summary": "Run a simulated order through the integration steps (sandbox host only; 404 in production). Writes no order and moves no money.",
        "description": "Needs `sandbox:write`. `order` is validated exactly as `createOrder` validates its body, so a malformed order is\nrefused `400` as an order would be, and no run is made. The key, the contract and the product's availability are\nchecked for real; acceptance, processing and the outcome are the scenario's, simulated, against the order id\n`ord_00000000000000000000000000`, which no order can have. No balance, statement, order list, provider or chain\nis touched. With `webhook_endpoint_id`, one test event of the outcome's type (`\"test\": true`, synthetic object) is\nsigned and delivered to that endpoint as any event is, and the run shows its real answer. Read the run back with\nthis key (`getSandboxTestRun`) to pass its status-retrieval step. At most 60 runs an hour per organisation; the\nwebhook part also spends the endpoint's 20 test events an hour.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKeyOptional"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TestRunCreate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A replay of an earlier request with the same Idempotency-Key: the run it made, as it is now. Nothing is run again.",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              },
              "Idempotent-Replayed": {
                "schema": {
                  "type": "string",
                  "enum": [
                    "true"
                  ]
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TestRun"
                }
              }
            }
          },
          "201": {
            "description": "The run, with every step it could finish now",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TestRun"
                }
              }
            }
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      },
      "get": {
        "tags": [
          "Sandbox"
        ],
        "operationId": "listSandboxTestRuns",
        "summary": "The organisation's test runs, newest first (sandbox host only). Kept 30 days.",
        "description": "Needs `orders:read`.",
        "parameters": [
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "$ref": "#/components/parameters/Cursor"
          }
        ],
        "responses": {
          "200": {
            "description": "Test runs",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TestRunList"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/sandbox/test-runs/{id}": {
      "get": {
        "tags": [
          "Sandbox"
        ],
        "operationId": "getSandboxTestRun",
        "summary": "One test run (sandbox host only). The first read with a key passes the run's status_retrieval step.",
        "description": "Needs `orders:read`. Another organisation's run is `404 not_found`, exactly like an unknown id.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/TestRunId"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The run",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TestRun"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "default": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    }
  },
  "webhooks": {
    "event": {
      "post": {
        "operationId": "receiveEvent",
        "summary": "An event sent to your endpoint, signed under Standard Webhooks v1",
        "description": "Verify the signature over the raw body before parsing it, reject a timestamp more than 5 minutes from your clock, and deduplicate by webhook-id. Retries and replays carry the same webhook-id and body, with a new timestamp and signature. During the 24 hours after a secret rotation the signature header holds one signature per active secret. Then fetch the object before releasing value to your own customer. A test event (sendWebhookTestEvent) is signed and delivered the same way and says `\"test\": true`; its object is synthetic and fetching it is 404.\n",
        "security": [],
        "parameters": [
          {
            "name": "webhook-id",
            "in": "header",
            "required": true,
            "description": "The event id. The same on every retry and replay",
            "schema": {
              "type": "string",
              "pattern": "^evt_[0-9A-HJKMNP-TV-Z]{26}$"
            }
          },
          {
            "name": "webhook-timestamp",
            "in": "header",
            "required": true,
            "description": "Whole seconds since the Unix epoch when this attempt was signed",
            "schema": {
              "type": "string",
              "pattern": "^[0-9]{1,12}$"
            }
          },
          {
            "name": "webhook-signature",
            "in": "header",
            "required": true,
            "description": "Space-separated `v1,<base64>` signatures, each HMAC-SHA256 under the bytes of one secret (the base64 after `whsec_`) over `<webhook-id>.<webhook-timestamp>.<raw body>`",
            "schema": {
              "type": "string",
              "pattern": "^v1,[A-Za-z0-9+/=]+( v1,[A-Za-z0-9+/=]+)*$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Event"
              }
            }
          }
        },
        "responses": {
          "410": {
            "description": "Gone. The endpoint is disabled and receives nothing more"
          },
          "2XX": {
            "description": "Received. Any 2xx counts as delivered: answer within 15 seconds and process afterwards"
          },
          "default": {
            "description": "A failure, 3xx included (redirects are never followed). Retried after 5 s, 5 min, 30 min, 2 h, 5 h, 10 h, 14 h, 20 h and 24 h, honouring Retry-After; then the endpoint is disabled"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "nbk_{test|live}_{key_id}_{secret}{checksum}",
        "description": "Every request is verified in the database; no verification is cached. A revoked key is therefore refused from the next request on (`invalid_api_key`); a request already authenticated finishes. An expired key with its correct secret is `key_expired`; any other failure is `invalid_api_key`. A key of the other environment is `key_environment_mismatch`, refused before any lookup.\nA key may name the addresses it is used from; while that restriction is switched on, a request from any other address is `ip_not_allowed` (403) and nothing is read or written. The address is the connection's, or, behind Nasfam's own proxies only, the one they forwarded.\n"
      }
    },
    "parameters": {
      "IdempotencyKeyRequired": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": true,
        "description": "Bound permanently to the operation it created (an order, a simulated funding). Reuse it on every retry of the same request.",
        "schema": {
          "type": "string",
          "pattern": "^[A-Za-z0-9_-]{16,64}$"
        }
      },
      "IdempotencyKeyOptional": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": false,
        "description": "Bound permanently, in the database, to what the first request made (a quote, an endpoint, a rotation, a delivery replay), as a money operation's key is: a retry with the same key and request answers 200 with Idempotent-Replayed: true and repeats nothing, and the same key with another request or on another operation is 422 idempotency_key_reused. A replay never returns a secret. Without a key, every request is performed.",
        "schema": {
          "type": "string",
          "pattern": "^[A-Za-z0-9_-]{16,64}$"
        }
      },
      "Limit": {
        "name": "limit",
        "in": "query",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100,
          "default": 20
        }
      },
      "Cursor": {
        "name": "cursor",
        "in": "query",
        "schema": {
          "type": "string",
          "maxLength": 256
        }
      }
    },
    "headers": {
      "RateLimitPolicy": {
        "description": "draft-ietf-httpapi-ratelimit-headers-11. A Structured Field list with one item per bucket the request drew on (`orders`, `quotes`, `quotes_daily`, `reads`, `webhooks`, `lookups`, `lookups_org`, `lookups_daily`), each `\"<bucket>\";q=<quota>;w=<window seconds>`. No partition key (`pk`) is sent.\n",
        "schema": {
          "type": "string"
        }
      },
      "RateLimit": {
        "description": "draft-ietf-httpapi-ratelimit-headers-11. The same buckets, each `\"<bucket>\";r=<whole requests remaining, never negative>;t=<seconds until the quota is fully available again>`.\n",
        "schema": {
          "type": "string"
        }
      }
    },
    "responses": {
      "RateLimited": {
        "description": "Too many requests (`rate_limited`), or your queued orders are at your cap (`queue_limit`). A bucket that cannot be read at once because of contention is answered here too, never waited on. Honour Retry-After.\n",
        "headers": {
          "Request-Id": {
            "schema": {
              "type": "string"
            }
          },
          "Retry-After": {
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "description": "Seconds to wait before retrying"
          },
          "RateLimit": {
            "$ref": "#/components/headers/RateLimit"
          },
          "RateLimit-Policy": {
            "$ref": "#/components/headers/RateLimitPolicy"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      },
      "PayloadTooLarge": {
        "description": "The request body is over 16 KB (`payload_too_large`). Refused before authentication; nothing is read further.",
        "headers": {
          "Request-Id": {
            "schema": {
              "type": "string"
            }
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      },
      "Problem": {
        "description": "Error (RFC 9457). A 503 `service_unavailable` with Retry-After means the request was not processed: the rate limiter or the database could not answer, and the API refuses rather than serve unlimited (reads included). For a money-moving operation, retrying with the same Idempotency-Key is always safe.\n",
        "headers": {
          "Request-Id": {
            "schema": {
              "type": "string"
            }
          },
          "Retry-After": {
            "schema": {
              "type": "integer"
            },
            "description": "On 429 and some 503 responses"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      }
    },
    "schemas": {
      "Money": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "amount",
          "currency"
        ],
        "properties": {
          "amount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100000000000,
            "description": "USD, in cents"
          },
          "currency": {
            "type": "string",
            "enum": [
              "USD"
            ],
            "description": "USD"
          }
        }
      },
      "SignedMoney": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "amount",
          "currency"
        ],
        "properties": {
          "amount": {
            "type": "integer",
            "minimum": -100000000000,
            "maximum": 100000000000
          },
          "currency": {
            "type": "string",
            "enum": [
              "USD"
            ]
          }
        }
      },
      "ListMeta": {
        "type": "object",
        "required": [
          "has_more",
          "next_cursor"
        ],
        "properties": {
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "ProductId": {
        "type": "string",
        "enum": [
          "telegram_stars",
          "telegram_premium"
        ],
        "description": "telegram_premium is a Telegram Premium subscription for 3, 6 or 12 months, given to the account at the username. An order succeeds only when the provider's own record of our one purchase for it, found by our reference, says it was delivered; a purchase answer, a timeout or an undocumented status is never taken as delivery. Until then the order is processing (or under_review, when people must decide) and its amount stays held. It fails, and the amount is released, only on the provider's documented failure or a two-person decision."
      },
      "Product": {
        "type": "object",
        "required": [
          "id",
          "name",
          "status",
          "provisional",
          "available",
          "selection",
          "recipient"
        ],
        "description": "Read from approved offer configuration. Limits are provisional until provider capabilities are verified.",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/ProductId"
          },
          "name": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "sandbox",
              "planned",
              "live"
            ],
            "description": "sandbox = simulated only; planned = not orderable"
          },
          "provisional": {
            "type": "boolean"
          },
          "available": {
            "type": "boolean"
          },
          "selection": {
            "oneOf": [
              {
                "type": "object",
                "required": [
                  "type",
                  "min",
                  "max",
                  "step"
                ],
                "properties": {
                  "type": {
                    "const": "quantity"
                  },
                  "min": {
                    "type": "integer"
                  },
                  "max": {
                    "type": "integer",
                    "description": "The most one order may buy: the offer's maximum, bounded by what its provider is verified to accept. An order above it is refused whole, never split"
                  },
                  "step": {
                    "type": "integer"
                  }
                }
              },
              {
                "type": "object",
                "required": [
                  "type",
                  "allowed"
                ],
                "properties": {
                  "type": {
                    "const": "months"
                  },
                  "allowed": {
                    "type": "array",
                    "items": {
                      "type": "integer",
                      "enum": [
                        3,
                        6,
                        12
                      ]
                    }
                  }
                }
              }
            ]
          },
          "recipient": {
            "type": "object",
            "properties": {
              "type": {
                "const": "telegram_username"
              }
            }
          }
        }
      },
      "TelegramUsername": {
        "type": "string",
        "pattern": "^@?[A-Za-z0-9_]{5,32}$",
        "description": "Normalised server-side (leading @ or t.me/ removed, lower-cased)."
      },
      "TelegramRecipientInput": {
        "type": "string",
        "maxLength": 64,
        "pattern": "^(?:@|(?:[Hh][Tt][Tt][Pp][Ss]?://)?[Tt]\\.[Mm][Ee]/)?[A-Za-z0-9_]{5,32}/?$",
        "description": "A username as a customer types it: `name`, `@name`, `t.me/name`, or that link with its scheme. Normalised server-side (the @ or link removed, lower-cased); the answer carries the normalised username."
      },
      "RecipientLookupId": {
        "type": "string",
        "pattern": "^rlk_[0-9A-HJKMNP-TV-Z]{26}$"
      },
      "RecipientLookupRequest": {
        "oneOf": [
          {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "product",
              "telegram_username",
              "quantity"
            ],
            "properties": {
              "product": {
                "const": "telegram_stars"
              },
              "telegram_username": {
                "$ref": "#/components/schemas/TelegramRecipientInput"
              },
              "quantity": {
                "type": "integer",
                "minimum": 1,
                "maximum": 1000000,
                "description": "The quantity you will quote; bounded further by the offer configuration. Telegram Stars are 50 to 100,000 per order; GET /products gives the maximum in force. Above it the request is refused (400 invalid_request at /quantity), never split: for more, place several orders, each with its own quote and Idempotency-Key"
              }
            }
          },
          {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "product",
              "telegram_username",
              "months"
            ],
            "properties": {
              "product": {
                "const": "telegram_premium"
              },
              "telegram_username": {
                "$ref": "#/components/schemas/TelegramRecipientInput"
              },
              "months": {
                "type": "integer",
                "enum": [
                  3,
                  6,
                  12
                ]
              }
            }
          }
        ]
      },
      "RecipientLookup": {
        "type": "object",
        "required": [
          "id",
          "found",
          "resolution_status",
          "product_eligibility",
          "telegram_username",
          "display_name",
          "photo_url",
          "product",
          "selection",
          "expires_at",
          "created_at",
          "lookup_source"
        ],
        "description": "The account the provider found at a username. Show `display_name` and `photo_url` (when not null) and let your customer confirm before you quote; never present it as a verified identity. Nothing else is returned because the provider returns nothing else: no stable account id, no Premium status, no promise of delivery. `id` is the recipient reference a quote or an order cites.",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/RecipientLookupId"
          },
          "found": {
            "type": "boolean",
            "const": true,
            "description": "An account was found at the username. A lookup that finds nobody is 422 recipient_not_found."
          },
          "resolution_status": {
            "type": "string",
            "const": "found",
            "description": "How the username resolved. Every other resolution is a Problem with its own code: recipient_not_found, recipient_not_eligible, provider_unavailable."
          },
          "product_eligibility": {
            "type": "string",
            "const": "not_refused",
            "description": "The provider did not refuse this account for this product and selection. It states no eligibility of its own, so this is not a promise of delivery: a refusal at purchase fails the order and releases its hold. An account the provider refuses is 422 recipient_not_eligible."
          },
          "telegram_username": {
            "type": "string",
            "description": "The normalised username, as quotes and orders carry it"
          },
          "display_name": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 64,
            "description": "The name the provider returned, cleaned of control characters; null when it returned none"
          },
          "photo_url": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 2048,
            "description": "An https URL of the profile photo on a Telegram image host, as returned; null when the provider returned none or anything else. Load it in an image element only; it may stop working after expires_at"
          },
          "product": {
            "$ref": "#/components/schemas/ProductId"
          },
          "selection": {
            "$ref": "#/components/schemas/Selection"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "Until when a quote may cite this lookup"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "lookup_source": {
            "type": "string",
            "enum": [
              "provider",
              "simulated"
            ],
            "description": "Who answered the lookup. `provider`: the Telegram provider's read-only search found this account (always in Live; in the sandbox while real lookups are on, for any username that is not a nasfam_test_ scenario). `simulated`: the sandbox's simulator answered, and the account is a sample. In the sandbox the quote, the order and its delivery are synthetic either way: nothing is bought or sent to Telegram. Tolerate new values."
          }
        }
      },
      "QuoteRequest": {
        "oneOf": [
          {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "product",
              "telegram_username",
              "quantity"
            ],
            "properties": {
              "product": {
                "const": "telegram_stars"
              },
              "telegram_username": {
                "$ref": "#/components/schemas/TelegramUsername"
              },
              "quantity": {
                "type": "integer",
                "minimum": 1,
                "maximum": 1000000,
                "description": "Bounded further by the offer configuration. Telegram Stars are 50 to 100,000 per order; GET /products gives the maximum in force. Above it the request is refused (400 invalid_request at /quantity), never split: for more, place several orders, each with its own quote and Idempotency-Key"
              },
              "recipient_lookup": {
                "$ref": "#/components/schemas/RecipientLookupId"
              },
              "pay_with": {
                "type": "string",
                "enum": [
                  "auto",
                  "usd"
                ],
                "description": "A USD organisation always pays in USD; both values mean that"
              }
            }
          },
          {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "product",
              "telegram_username",
              "months"
            ],
            "properties": {
              "product": {
                "const": "telegram_premium"
              },
              "telegram_username": {
                "$ref": "#/components/schemas/TelegramUsername"
              },
              "months": {
                "type": "integer",
                "enum": [
                  3,
                  6,
                  12
                ]
              },
              "recipient_lookup": {
                "$ref": "#/components/schemas/RecipientLookupId"
              },
              "pay_with": {
                "type": "string",
                "enum": [
                  "auto",
                  "usd"
                ],
                "description": "A USD organisation always pays in USD; both values mean that"
              }
            }
          }
        ]
      },
      "Recipient": {
        "type": "object",
        "required": [
          "telegram_username",
          "display_name",
          "found"
        ],
        "description": "Quote responses only. The display name is never stored on orders or sent in webhooks.",
        "properties": {
          "telegram_username": {
            "type": "string"
          },
          "display_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "found": {
            "type": "boolean",
            "const": true,
            "description": "The provider found an account at the username. Not a verification of who owns it."
          }
        }
      },
      "OrderRecipient": {
        "type": "object",
        "required": [
          "telegram_username"
        ],
        "properties": {
          "telegram_username": {
            "type": "string"
          }
        }
      },
      "Selection": {
        "type": "object",
        "properties": {
          "quantity": {
            "type": "integer"
          },
          "months": {
            "type": "integer"
          }
        }
      },
      "Quote": {
        "type": "object",
        "required": [
          "id",
          "product",
          "selection",
          "recipient",
          "amount",
          "pricing_version",
          "expires_at",
          "created_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^quo_[0-9A-HJKMNP-TV-Z]{26}$"
          },
          "product": {
            "$ref": "#/components/schemas/ProductId"
          },
          "selection": {
            "$ref": "#/components/schemas/Selection"
          },
          "recipient": {
            "$ref": "#/components/schemas/Recipient"
          },
          "recipient_lookup": {
            "type": [
              "string",
              "null"
            ],
            "description": "The recipient lookup this quote was bound to, or null"
          },
          "amount": {
            "$ref": "#/components/schemas/Money"
          },
          "settlement": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/GramSettlement"
              },
              {
                "$ref": "#/components/schemas/UsdSettlement"
              }
            ]
          },
          "pricing_version": {
            "type": "string"
          },
          "price_basis": {
            "allOf": [
              {
                "$ref": "#/components/schemas/PriceBasis"
              }
            ],
            "description": "USD quotes: how this price was set and when a new quote could differ"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "breakdown": {
            "$ref": "#/components/schemas/QuoteBreakdown"
          },
          "payment": {
            "$ref": "#/components/schemas/QuotePayment"
          }
        }
      },
      "Metadata": {
        "type": "object",
        "maxProperties": 20,
        "propertyNames": {
          "maxLength": 40,
          "pattern": "^[^\\u0000\\uD800-\\uDFFF]*$"
        },
        "additionalProperties": {
          "type": "string",
          "maxLength": 500,
          "pattern": "^[^\\u0000\\uD800-\\uDFFF]*$"
        }
      },
      "OrderFromQuote": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "quote_id"
        ],
        "properties": {
          "quote_id": {
            "type": "string",
            "pattern": "^quo_[0-9A-HJKMNP-TV-Z]{26}$"
          },
          "recipient_lookup": {
            "allOf": [
              {
                "$ref": "#/components/schemas/RecipientLookupId"
              }
            ],
            "description": "The lookup this quote was bound to, to have the order refused if it is any other: 409 recipient_mismatch. Part of the request an Idempotency-Key binds."
          },
          "reference": {
            "type": "string",
            "maxLength": 64,
            "pattern": "^[A-Za-z0-9._:-]{1,64}$"
          },
          "metadata": {
            "$ref": "#/components/schemas/Metadata"
          }
        }
      },
      "OrderDirect": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "product",
          "telegram_username",
          "max_amount"
        ],
        "properties": {
          "product": {
            "$ref": "#/components/schemas/ProductId"
          },
          "telegram_username": {
            "$ref": "#/components/schemas/TelegramUsername"
          },
          "quantity": {
            "type": "integer",
            "minimum": 1,
            "maximum": 1000000,
            "description": "Bounded further by the offer configuration. Telegram Stars are 50 to 100,000 per order; GET /products gives the maximum in force. Above it the request is refused (400 invalid_request at /quantity), never split: for more, place several orders, each with its own quote and Idempotency-Key"
          },
          "months": {
            "type": "integer",
            "enum": [
              3,
              6,
              12
            ]
          },
          "max_amount": {
            "$ref": "#/components/schemas/Money"
          },
          "recipient_lookup": {
            "allOf": [
              {
                "$ref": "#/components/schemas/RecipientLookupId"
              }
            ],
            "description": "The lookup your customer confirmed. The order's own quote is bound to it and refused as a quote citing it is. Part of the request an Idempotency-Key binds."
          },
          "reference": {
            "type": "string",
            "maxLength": 64,
            "pattern": "^[A-Za-z0-9._:-]{1,64}$"
          },
          "metadata": {
            "$ref": "#/components/schemas/Metadata"
          }
        }
      },
      "ProductInput": {
        "type": "string",
        "enum": [
          "stars",
          "premium",
          "telegram_stars",
          "telegram_premium"
        ],
        "description": "`stars` is `telegram_stars` and `premium` is `telegram_premium`; answers always carry the full id."
      },
      "UsdCeiling": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "amount",
          "currency"
        ],
        "description": "The most this order may cost, in USD cents. An order that would cost more is refused 409 price_changed and nothing is held.",
        "properties": {
          "amount": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100000000000,
            "description": "USD, in cents"
          },
          "currency": {
            "type": "string",
            "const": "USD"
          }
        }
      },
      "OrderStars": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "product",
          "username",
          "quantity"
        ],
        "description": "The quickest Telegram Stars order (draft.10): no quote, lookup or id needed.",
        "properties": {
          "product": {
            "type": "string",
            "enum": [
              "stars",
              "telegram_stars"
            ]
          },
          "username": {
            "$ref": "#/components/schemas/TelegramRecipientInput"
          },
          "quantity": {
            "type": "integer",
            "minimum": 1,
            "maximum": 1000000,
            "description": "Bounded further by the offer configuration. Telegram Stars are 50 to 100,000 per order; GET /products gives the maximum in force. Above it the request is refused (400 invalid_request at /quantity), never split"
          },
          "max_amount": {
            "$ref": "#/components/schemas/UsdCeiling"
          },
          "reference": {
            "type": "string",
            "maxLength": 64,
            "pattern": "^[A-Za-z0-9._:-]{1,64}$"
          },
          "metadata": {
            "$ref": "#/components/schemas/Metadata"
          }
        }
      },
      "OrderPremium": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "product",
          "username",
          "months"
        ],
        "description": "The quickest Telegram Premium order (draft.10): no quote, lookup or id needed.",
        "properties": {
          "product": {
            "type": "string",
            "enum": [
              "premium",
              "telegram_premium"
            ]
          },
          "username": {
            "$ref": "#/components/schemas/TelegramRecipientInput"
          },
          "months": {
            "type": "integer",
            "enum": [
              3,
              6,
              12
            ]
          },
          "max_amount": {
            "$ref": "#/components/schemas/UsdCeiling"
          },
          "reference": {
            "type": "string",
            "maxLength": 64,
            "pattern": "^[A-Za-z0-9._:-]{1,64}$"
          },
          "metadata": {
            "$ref": "#/components/schemas/Metadata"
          }
        }
      },
      "RecipientCheck": {
        "type": "object",
        "required": [
          "username",
          "product",
          "found",
          "display_name",
          "eligibility",
          "reason"
        ],
        "description": "GET /v1/recipients/lookup. Holds no id: an order never needs one. Never a verified identity and never a promise of delivery: a refusal at purchase fails the order and releases its hold.",
        "properties": {
          "username": {
            "type": "string",
            "description": "The normalised username, as an order carries it"
          },
          "product": {
            "$ref": "#/components/schemas/ProductId"
          },
          "found": {
            "type": "boolean",
            "description": "The provider found an account at the username"
          },
          "display_name": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 64,
            "description": "The name the provider returned for an account it did not refuse, cleaned of control characters; null otherwise"
          },
          "eligibility": {
            "type": "string",
            "enum": [
              "not_refused",
              "refused"
            ],
            "description": "`not_refused`: the provider did not refuse this account for this product (it states no eligibility of its own). `refused`: an order would be refused. Tolerate new values."
          },
          "reason": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "recipient_not_found",
              "recipient_not_eligible",
              null
            ],
            "description": "Why, when `eligibility` is refused; null otherwise. Tolerate new values."
          }
        }
      },
      "TestRunId": {
        "type": "string",
        "pattern": "^itr_[0-9A-HJKMNP-TV-Z]{26}$"
      },
      "TestRunScenario": {
        "type": "string",
        "enum": [
          "succeeded",
          "provider_delay",
          "fulfilment_failed",
          "insufficient_funds",
          "recipient_not_found",
          "recipient_not_eligible"
        ],
        "description": "What the simulated order does. An invalid request is tested by sending one: it is refused 400 as createOrder would refuse it, and no run is made."
      },
      "TestRunCreate": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "scenario",
          "order"
        ],
        "properties": {
          "scenario": {
            "$ref": "#/components/schemas/TestRunScenario"
          },
          "order": {
            "$ref": "#/components/schemas/OrderDirect"
          },
          "webhook_endpoint_id": {
            "type": "string",
            "pattern": "^whe_[0-9A-HJKMNP-TV-Z]{26}$"
          }
        }
      },
      "TestRunStep": {
        "type": "object",
        "required": [
          "step",
          "basis",
          "state",
          "at"
        ],
        "properties": {
          "step": {
            "type": "string",
            "enum": [
              "authentication",
              "validation",
              "product_access",
              "order_acceptance",
              "processing",
              "outcome",
              "status_retrieval",
              "webhook_event",
              "webhook_delivery"
            ]
          },
          "basis": {
            "type": "string",
            "enum": [
              "real",
              "simulated"
            ],
            "description": "`real`: checked against this organisation's records. `simulated`: the scenario's answer; no order exists."
          },
          "state": {
            "type": "string",
            "enum": [
              "passed",
              "failed",
              "simulated",
              "checking",
              "not_applicable",
              "skipped"
            ]
          },
          "at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "status": {
            "type": [
              "integer",
              "null"
            ],
            "description": "The HTTP status a real createOrder would have answered at this step, where one applies."
          },
          "code": {
            "type": [
              "string",
              "null"
            ],
            "description": "A problem code (a simulated refusal, or a real product refusal), or a webhook failure class."
          },
          "event_id": {
            "type": "string"
          },
          "delivery_id": {
            "type": "string"
          }
        }
      },
      "TestRun": {
        "type": "object",
        "required": [
          "id",
          "created_at",
          "environment",
          "started_by",
          "key_id",
          "product",
          "scenario",
          "state",
          "outcome",
          "simulated_order_id",
          "webhook_endpoint_id",
          "steps",
          "elapsed_ms",
          "docs_url"
        ],
        "properties": {
          "id": {
            "$ref": "#/components/schemas/TestRunId"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "environment": {
            "const": "sandbox"
          },
          "started_by": {
            "type": "string",
            "enum": [
              "key",
              "member"
            ]
          },
          "key_id": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^[a-z2-7]{16}$"
          },
          "product": {
            "$ref": "#/components/schemas/ProductId"
          },
          "scenario": {
            "$ref": "#/components/schemas/TestRunScenario"
          },
          "state": {
            "type": "string",
            "enum": [
              "completed",
              "waiting"
            ],
            "description": "`waiting`: the status read or the webhook delivery has not happened yet."
          },
          "outcome": {
            "type": "string",
            "enum": [
              "succeeded",
              "failed",
              "processing",
              "refused"
            ],
            "description": "The simulated order's outcome. Never a real order."
          },
          "simulated_order_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "ord_00000000000000000000000000 for an accepted simulation, which no order can have: GET /orders/{id} is 404 for it. Null for a refusal."
          },
          "webhook_endpoint_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "steps": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TestRunStep"
            }
          },
          "elapsed_ms": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 0,
            "description": "From creation to the last step finished; null while waiting."
          },
          "docs_url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "TestRunList": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ListMeta"
          },
          {
            "type": "object",
            "required": [
              "data"
            ],
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/TestRun"
                }
              }
            }
          }
        ]
      },
      "OrderStatus": {
        "type": "string",
        "enum": [
          "processing",
          "succeeded",
          "failed",
          "under_review"
        ]
      },
      "Order": {
        "type": "object",
        "required": [
          "id",
          "environment",
          "status",
          "product",
          "selection",
          "recipient",
          "amount",
          "pricing_version",
          "version",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^ord_[0-9A-HJKMNP-TV-Z]{26}$"
          },
          "environment": {
            "type": "string",
            "enum": [
              "live",
              "sandbox"
            ]
          },
          "status": {
            "$ref": "#/components/schemas/OrderStatus"
          },
          "status_reason": {
            "type": [
              "string",
              "null"
            ],
            "description": "Stable codes. New values may be added; treat unknown values as informational.",
            "examples": [
              "provider_rejected",
              "recipient_not_eligible",
              "not_submitted_price_expired",
              "outcome_unconfirmed",
              "submission_unconfirmed",
              "provider_conflict"
            ]
          },
          "product": {
            "$ref": "#/components/schemas/ProductId"
          },
          "selection": {
            "$ref": "#/components/schemas/Selection"
          },
          "recipient": {
            "$ref": "#/components/schemas/OrderRecipient"
          },
          "amount": {
            "$ref": "#/components/schemas/Money"
          },
          "settlement": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/GramSettlement"
              },
              {
                "$ref": "#/components/schemas/UsdSettlement"
              }
            ]
          },
          "quote_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "recipient_lookup": {
            "type": [
              "string",
              "null"
            ],
            "description": "The recipient lookup this order's quote was bound to, or null. Not carried in events or webhooks."
          },
          "pricing_version": {
            "type": "string"
          },
          "reference": {
            "type": [
              "string",
              "null"
            ]
          },
          "metadata": {
            "$ref": "#/components/schemas/Metadata"
          },
          "version": {
            "type": "integer",
            "minimum": 1,
            "description": "Increases by one on every state change; order events by this"
          },
          "estimated_completion_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Estimate from the current queue and the approved provider rate; never a promise"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "completed_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "balance_after": {
            "type": "object",
            "description": "On the response that reserved the order only. The paying balance's available figure right after the reservation, from the ledger",
            "required": [
              "currency",
              "amount_minor"
            ],
            "properties": {
              "currency": {
                "type": "string",
                "enum": [
                  "USD",
                  "TON"
                ],
                "description": "USD in micro-dollars, or TON (GRAM) in nanogram"
              },
              "amount_minor": {
                "type": "string",
                "pattern": "^(0|[1-9][0-9]{0,18})$"
              }
            }
          }
        }
      },
      "Balance": {
        "type": "object",
        "required": [
          "available",
          "held",
          "pending_funding",
          "updated_at"
        ],
        "properties": {
          "available": {
            "$ref": "#/components/schemas/Money"
          },
          "held": {
            "$ref": "#/components/schemas/Money"
          },
          "pending_funding": {
            "$ref": "#/components/schemas/Money"
          },
          "total": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Money"
              }
            ],
            "description": "Available plus held, rounded down once from the exact units. Never includes on_hold or incoming."
          },
          "on_hold": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Money"
              }
            ],
            "description": "Credited and not spendable yet. The same figure as pending_funding, which keeps its meaning."
          },
          "incoming": {
            "$ref": "#/components/schemas/BalanceIncoming"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "gram": {
            "$ref": "#/components/schemas/GramBalance"
          },
          "spending_currency": {
            "$ref": "#/components/schemas/SpendingCurrency"
          },
          "usd": {
            "$ref": "#/components/schemas/UsdBalance"
          },
          "headline": {
            "$ref": "#/components/schemas/BalanceHeadline"
          },
          "activity": {
            "$ref": "#/components/schemas/BalanceActivity"
          },
          "display": {
            "allOf": [
              {
                "$ref": "#/components/schemas/DisplayEquivalent"
              }
            ],
            "description": "The available balance of the organisation's spending currency (available, or gram.available_nanogram for a GRAM organisation) in the reader's display currency, indicative, at the newest rates. Every other field is unchanged."
          }
        }
      },
      "BalanceIncoming": {
        "type": "object",
        "description": "Chain deposits seen and not yet credited, counted and summed per asset in its own unit (nanogram for GRAM). Never in available or total.",
        "required": [
          "count",
          "by_asset"
        ],
        "properties": {
          "count": {
            "type": "integer",
            "minimum": 0
          },
          "by_asset": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "asset",
                "count",
                "amount_minor"
              ],
              "properties": {
                "asset": {
                  "type": "string",
                  "enum": [
                    "GRAM"
                  ]
                },
                "count": {
                  "type": "integer",
                  "minimum": 1
                },
                "amount_minor": {
                  "type": "string",
                  "pattern": "^[0-9]{1,30}$"
                }
              }
            }
          }
        }
      },
      "Nanogram": {
        "type": "string",
        "pattern": "^(0|[1-9][0-9]{0,15})$",
        "description": "An integer number of nanogram (1 GRAM = 1,000,000,000), as a string"
      },
      "GramSettlement": {
        "type": "object",
        "description": "Present when the organisation pays with GRAM. What the order charges, as GRAM, and the price and rate it came from.",
        "required": [
          "currency",
          "asset",
          "amount_nanogram",
          "amount_gram",
          "price_usd_micros",
          "price_book_version",
          "rounding",
          "rate"
        ],
        "properties": {
          "currency": {
            "type": "string",
            "enum": [
              "TON"
            ],
            "description": "The ledger currency of GRAM"
          },
          "asset": {
            "type": "string",
            "enum": [
              "GRAM"
            ]
          },
          "amount_nanogram": {
            "$ref": "#/components/schemas/Nanogram"
          },
          "amount_gram": {
            "type": "string",
            "pattern": "^[0-9]+\\.[0-9]{9}$",
            "description": "The same amount as GRAM, for display"
          },
          "price_usd_micros": {
            "type": "string",
            "pattern": "^[1-9][0-9]{0,12}$"
          },
          "price_book_version": {
            "type": "integer",
            "minimum": 1
          },
          "rounding": {
            "type": "string",
            "enum": [
              "up_to_the_nanogram"
            ]
          },
          "rate": {
            "type": "object",
            "required": [
              "pair",
              "usd_per_gram",
              "usd_micros_per_gram",
              "source_time"
            ],
            "properties": {
              "pair": {
                "type": "string",
                "enum": [
                  "GRAM/USD"
                ]
              },
              "usd_per_gram": {
                "type": "string",
                "description": "Decimal, 6 places, for display; the exact rate is usd_micros_per_gram"
              },
              "usd_micros_per_gram": {
                "$ref": "#/components/schemas/Fraction"
              },
              "source_time": {
                "type": "string",
                "format": "date-time"
              }
            }
          }
        }
      },
      "Fraction": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "numerator",
          "denominator"
        ],
        "properties": {
          "numerator": {
            "type": "string",
            "pattern": "^[1-9][0-9]{0,30}$"
          },
          "denominator": {
            "type": "string",
            "pattern": "^[1-9][0-9]{0,30}$"
          }
        }
      },
      "GramBalance": {
        "type": "object",
        "description": "Present when the organisation holds GRAM accounts. GRAM is a deposited asset, shown in its own unit. While deposits convert to USD this is only what is held or still being spent.",
        "required": [
          "currency",
          "asset",
          "available_nanogram",
          "held_nanogram",
          "pending_nanogram"
        ],
        "properties": {
          "currency": {
            "type": "string",
            "enum": [
              "TON"
            ]
          },
          "asset": {
            "type": "string",
            "enum": [
              "GRAM"
            ]
          },
          "available_nanogram": {
            "$ref": "#/components/schemas/Nanogram"
          },
          "held_nanogram": {
            "$ref": "#/components/schemas/Nanogram"
          },
          "pending_nanogram": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Nanogram"
              }
            ],
            "description": "Deposits received and held for review; not spendable"
          },
          "estimated_usd": {
            "$ref": "#/components/schemas/EstimatedUsd"
          }
        }
      },
      "MarketRate": {
        "type": "object",
        "required": [
          "pair",
          "available"
        ],
        "properties": {
          "pair": {
            "type": "string",
            "enum": [
              "GRAM/USD"
            ]
          },
          "available": {
            "type": "boolean"
          },
          "usd_per_gram": {
            "type": "string"
          },
          "usd_micros_per_gram": {
            "$ref": "#/components/schemas/Fraction"
          },
          "source_time": {
            "type": "string",
            "format": "date-time"
          },
          "valid_until": {
            "type": "string",
            "format": "date-time"
          },
          "quotable": {
            "type": "boolean",
            "description": "Whether a quote may be priced at it now; false means stale"
          }
        }
      },
      "DisplayRate": {
        "type": "object",
        "required": [
          "pair",
          "available"
        ],
        "properties": {
          "pair": {
            "type": "string",
            "enum": [
              "USD/EUR",
              "USD/GBP"
            ]
          },
          "available": {
            "type": "boolean"
          },
          "per_usd": {
            "type": "string"
          },
          "rate": {
            "$ref": "#/components/schemas/Fraction"
          },
          "source_time": {
            "type": "string",
            "format": "date-time"
          },
          "valid_until": {
            "type": "string",
            "format": "date-time"
          },
          "display_only": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "state": {
            "$ref": "#/components/schemas/DisplayState"
          },
          "agreement": {
            "$ref": "#/components/schemas/DisplayAgreement"
          },
          "shown": {
            "type": "boolean",
            "description": "Whether a figure may be shown for this pair: only when it is fresh and two independent sources agree. When false a page shows no figure, whatever per_usd says (per_usd is the newest single reading, kept for older clients)."
          },
          "judged": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/DisplayJudgement"
              },
              {
                "type": "null"
              }
            ]
          },
          "tolerance_bps": {
            "type": "integer",
            "minimum": 0,
            "description": "How far apart the sources may be"
          },
          "deviation_bps": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 0,
            "description": "The widest gap between the primary and a check, rounded up"
          }
        }
      },
      "DisplayCurrency": {
        "type": "string",
        "enum": [
          "USD",
          "EUR",
          "GBP"
        ],
        "description": "A currency a figure may be shown in, indicatively (0300). Display only: never a balance, a price, a quote, a charge or a settlement. The served list is the server's configuration; a client ignores a value it does not know."
      },
      "DisplayState": {
        "type": "string",
        "enum": [
          "fresh",
          "stale",
          "unavailable"
        ],
        "description": "fresh: every source used is within its own freshness window. stale: one is older than that but not yet dropped. unavailable: no source is usable. Only fresh and agreeing is ever shown as a figure."
      },
      "DisplayAgreement": {
        "type": "string",
        "enum": [
          "agreeing",
          "disagreeing",
          "single_source",
          "no_source"
        ],
        "description": "agreeing: at least two independent sources, every one within the pair's tolerance of the primary. A single source or a disagreement shows no figure."
      },
      "DisplayJudgement": {
        "type": "object",
        "description": "The figure a page may show for a pair, from its primary source. Present only when the pair is shown.",
        "required": [
          "per_usd",
          "rate",
          "label",
          "source_time"
        ],
        "properties": {
          "per_usd": {
            "type": "string",
            "description": "Units of the quote currency per one USD, decimal, 6 places, rounded down"
          },
          "rate": {
            "$ref": "#/components/schemas/Fraction"
          },
          "label": {
            "type": "string",
            "description": "For example \"reference rate of 27 Oct 2026\""
          },
          "source_time": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "DisplayLeg": {
        "type": "object",
        "description": "One rate an equivalent is drawn from. GRAM/USD is the GRAM reference rate; the others are display rates.",
        "required": [
          "pair",
          "inverted",
          "state",
          "agreement",
          "shown",
          "label",
          "source_time"
        ],
        "properties": {
          "pair": {
            "type": "string",
            "enum": [
              "GRAM/USD",
              "USD/EUR",
              "USD/GBP"
            ]
          },
          "inverted": {
            "type": "boolean",
            "description": "true when the figure is divided by the rate"
          },
          "state": {
            "$ref": "#/components/schemas/DisplayState"
          },
          "agreement": {
            "$ref": "#/components/schemas/DisplayAgreement"
          },
          "shown": {
            "type": "boolean"
          },
          "label": {
            "type": [
              "string",
              "null"
            ]
          },
          "source_time": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        }
      },
      "DisplayEquivalent": {
        "type": "object",
        "description": "An indicative equivalent of one authoritative figure, in the reader's display currency. Display only: never charged, quoted, settled or booked, and changing the display currency changes no other field of any response. A figure (`amount`) is given only when every rate used is fresh and agreeing (`shown`); otherwise it is null and `state` and `agreement` say why. A same-currency figure is the authoritative one, unconverted.",
        "required": [
          "currency",
          "chosen_by",
          "indicative",
          "of",
          "shown",
          "state",
          "agreement",
          "amount",
          "amount_minor",
          "per_unit",
          "rounding",
          "label",
          "as_of",
          "legs"
        ],
        "properties": {
          "currency": {
            "$ref": "#/components/schemas/DisplayCurrency"
          },
          "chosen_by": {
            "type": "string",
            "enum": [
              "member",
              "workspace",
              "suggested",
              "default"
            ],
            "description": "The member's own choice, then the workspace default, then the currency of the declared country, then USD"
          },
          "indicative": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "of": {
            "type": "object",
            "description": "The authoritative figure this is an equivalent of, in its ledger currency and minor unit",
            "required": [
              "currency",
              "amount_minor"
            ],
            "properties": {
              "currency": {
                "type": "string",
                "enum": [
                  "TON",
                  "USD"
                ],
                "description": "USD in micro-dollars, or TON (GRAM) in nanogram"
              },
              "amount_minor": {
                "type": "string",
                "pattern": "^-?(0|[1-9][0-9]{0,30})$"
              }
            }
          },
          "shown": {
            "type": "boolean"
          },
          "state": {
            "type": "string",
            "enum": [
              "fresh",
              "stale",
              "unavailable",
              "same_currency"
            ]
          },
          "agreement": {
            "type": "string",
            "enum": [
              "agreeing",
              "disagreeing",
              "single_source",
              "no_source",
              "not_needed"
            ]
          },
          "amount": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^-?[0-9]+\\.[0-9]{2}$",
            "description": "Decimal in the display currency, rounded toward zero to its minor unit. Null unless shown"
          },
          "amount_minor": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^-?(0|[1-9][0-9]{0,30})$",
            "description": "The same in the display currency's minor unit (cents, pence)"
          },
          "per_unit": {
            "type": [
              "string",
              "null"
            ],
            "description": "Display currency per one unit of the figure's currency, decimal, 9 places, rounded down. Null unless shown"
          },
          "rounding": {
            "type": "string",
            "enum": [
              "toward_zero_to_the_minor_unit"
            ]
          },
          "label": {
            "type": [
              "string",
              "null"
            ],
            "description": "For example \"Indicative, at the reference rate of 28 Oct 2026\". Null unless converted and shown"
          },
          "as_of": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "The oldest source time among the rates used. Null when none is usable"
          },
          "legs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DisplayLeg"
            }
          }
        }
      },
      "QuoteBreakdown": {
        "type": "object",
        "description": "What the quote is made of, restating figures the server already priced: nothing here is computed for display. `total` is exactly what an order from this quote holds from the balance. Charges are not itemised and no balance after the order is projected here: the server computes neither at quote time (the order's reservation is the real balance after it).",
        "required": [
          "price",
          "asset_equivalent",
          "total"
        ],
        "properties": {
          "price": {
            "$ref": "#/components/schemas/Money"
          },
          "asset_equivalent": {
            "description": "For an organisation that still spends GRAM, the price as GRAM at the quote's rate (its settlement). Otherwise null.",
            "oneOf": [
              {
                "type": "null"
              },
              {
                "type": "object",
                "required": [
                  "asset",
                  "amount_nanogram",
                  "amount_gram",
                  "rate"
                ],
                "properties": {
                  "asset": {
                    "type": "string",
                    "enum": [
                      "GRAM"
                    ]
                  },
                  "amount_nanogram": {
                    "$ref": "#/components/schemas/Nanogram"
                  },
                  "amount_gram": {
                    "type": "string",
                    "pattern": "^[0-9]+\\.[0-9]{9}$"
                  },
                  "rate": {
                    "type": "object",
                    "required": [
                      "pair",
                      "usd_per_gram",
                      "source_time"
                    ],
                    "properties": {
                      "pair": {
                        "type": "string",
                        "enum": [
                          "GRAM/USD"
                        ]
                      },
                      "usd_per_gram": {
                        "type": "string"
                      },
                      "source_time": {
                        "type": "string",
                        "format": "date-time"
                      }
                    }
                  }
                }
              }
            ]
          },
          "total": {
            "type": "object",
            "required": [
              "currency",
              "amount_minor"
            ],
            "properties": {
              "currency": {
                "type": "string",
                "enum": [
                  "TON",
                  "USD"
                ],
                "description": "USD in micro-dollars, or TON (GRAM) in nanogram"
              },
              "amount_minor": {
                "type": "string",
                "pattern": "^[1-9][0-9]{0,30}$"
              }
            }
          },
          "lines": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BreakdownLine"
            },
            "description": "USD organisations: each line of the total, computed once by the server; they sum to total_usd_micros"
          },
          "total_usd_micros": {
            "$ref": "#/components/schemas/UsdMicros"
          }
        }
      },
      "Rates": {
        "type": "object",
        "required": [
          "gram_usd",
          "display"
        ],
        "properties": {
          "gram_usd": {
            "$ref": "#/components/schemas/MarketRate"
          },
          "display": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DisplayRate"
            }
          }
        }
      },
      "PricePackage": {
        "type": "object",
        "required": [
          "product",
          "package_key",
          "selection",
          "price",
          "price_usd_micros",
          "indicative_nanogram",
          "display_amount"
        ],
        "properties": {
          "product": {
            "$ref": "#/components/schemas/ProductId"
          },
          "package_key": {
            "type": "string"
          },
          "selection": {
            "$ref": "#/components/schemas/Selection"
          },
          "price": {
            "$ref": "#/components/schemas/Money"
          },
          "price_usd_micros": {
            "type": "string",
            "pattern": "^[1-9][0-9]{0,12}$"
          },
          "available": {
            "type": "boolean",
            "description": "false: this package cannot be quoted right now (its price would fall outside the approved range); a quote is refused 503 pricing_unavailable"
          },
          "indicative_nanogram": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Nanogram"
              },
              {
                "type": "null"
              }
            ],
            "description": "Indicative only; the charge is the quote's"
          },
          "display_amount": {
            "type": [
              "string",
              "null"
            ],
            "description": "Estimated, in display_currency, never charged"
          }
        }
      },
      "PriceList": {
        "type": "object",
        "required": [
          "available",
          "data"
        ],
        "properties": {
          "available": {
            "type": "boolean",
            "description": "false: no price book is set in this environment, and GRAM quotes are refused"
          },
          "version": {
            "type": "integer",
            "minimum": 1
          },
          "label": {
            "type": "string"
          },
          "active_from": {
            "type": "string",
            "format": "date-time"
          },
          "rate": {
            "$ref": "#/components/schemas/MarketRate"
          },
          "display": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/DisplayRate"
              },
              {
                "type": "null"
              }
            ]
          },
          "price_basis": {
            "$ref": "#/components/schemas/PriceBasis"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PricePackage"
            }
          }
        }
      },
      "PriceBasis": {
        "type": "object",
        "required": [
          "kind",
          "currency",
          "updates",
          "quote_valid_seconds"
        ],
        "description": "How a USD price is set. usd_fixed: the price changes only when a new price book is published. usd_cost_plus: the price is the provider's cost in USD plus a fixed margin and a per-order fee, and changes only when that cost moves by more than reprice_threshold_bps. Either way a quote's price never changes once given, for quote_valid_seconds. New kinds may be added; treat an unknown kind as \"the quote's own price is the price\".",
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "usd_fixed",
              "usd_cost_plus"
            ]
          },
          "currency": {
            "type": "string",
            "enum": [
              "USD"
            ]
          },
          "updates": {
            "type": "string",
            "description": "The same, in words, for a person"
          },
          "reprice_threshold_bps": {
            "type": "integer",
            "minimum": 1,
            "description": "usd_cost_plus only: the cost move, in basis points, that changes a price"
          },
          "quote_valid_seconds": {
            "type": "integer",
            "minimum": 0
          },
          "quantities": {
            "type": "array",
            "description": "usd_cost_plus on the price list only: the whole quantities each product is priced for. A quantity in range is quoted with POST /v1/quotes.",
            "items": {
              "type": "object",
              "required": [
                "product",
                "min",
                "max"
              ],
              "properties": {
                "product": {
                  "$ref": "#/components/schemas/ProductId"
                },
                "min": {
                  "type": "integer",
                  "minimum": 1
                },
                "max": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          }
        }
      },
      "BalanceTransaction": {
        "type": "object",
        "required": [
          "id",
          "type",
          "amount",
          "available_after",
          "created_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^btx_[0-9A-HJKMNP-TV-Z]{26}$"
          },
          "type": {
            "type": "string",
            "enum": [
              "funding_credit",
              "order_reserve",
              "order_capture",
              "order_release",
              "adjustment",
              "reversal",
              "gram_conversion"
            ]
          },
          "amount": {
            "$ref": "#/components/schemas/SignedMoney",
            "description": "The signed change to the available balance. An order_capture moves held funds and shows 0."
          },
          "available_after": {
            "$ref": "#/components/schemas/Money"
          },
          "amount_micros": {
            "type": "string",
            "pattern": "^-?(0|[1-9][0-9]{0,18})$",
            "description": "USD: the exact change in micro-dollars (amount is it in cents, toward zero)"
          },
          "available_after_micros": {
            "type": "string",
            "pattern": "^(0|[1-9][0-9]{0,18})$",
            "description": "USD: the exact available balance after, in micro-dollars"
          },
          "order_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "funding_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "display": {
            "allOf": [
              {
                "$ref": "#/components/schemas/DisplayEquivalent"
              }
            ],
            "description": "amount in the reader's display currency at the display rates in force at created_at, never recalculated: a later rate never changes it, and a change of display currency changes only the currency it is looked up in."
          }
        }
      },
      "Funding": {
        "type": "object",
        "required": [
          "id",
          "amount",
          "status",
          "received_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^fnd_[0-9A-HJKMNP-TV-Z]{26}$"
          },
          "amount": {
            "$ref": "#/components/schemas/Money"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "credited",
              "held",
              "rejected"
            ]
          },
          "payer_name_masked": {
            "type": [
              "string",
              "null"
            ]
          },
          "received_at": {
            "type": "string",
            "format": "date-time"
          },
          "credited_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        }
      },
      "DepositAddress": {
        "type": "object",
        "required": [
          "object",
          "id",
          "asset",
          "network",
          "state",
          "address",
          "minimum_nanogram",
          "confirmation",
          "warnings"
        ],
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "deposit_address"
            ]
          },
          "id": {
            "type": "string",
            "pattern": "^dad_[0-9A-HJKMNP-TV-Z]{26}$"
          },
          "asset": {
            "type": "string",
            "enum": [
              "GRAM"
            ],
            "description": "Gram, the native coin of the TON network (formerly Toncoin). Never a jetton of the same name"
          },
          "network": {
            "type": "string",
            "enum": [
              "TON",
              "TON testnet"
            ]
          },
          "state": {
            "type": "string",
            "enum": [
              "preparing",
              "active"
            ],
            "description": "preparing: allocated, not yet independently verified; the address is not shown until active"
          },
          "address": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^(UQ|0Q)[A-Za-z0-9_-]{46}$",
            "description": "The non-bounceable user-friendly form; null while preparing"
          },
          "minimum_nanogram": {
            "type": "string",
            "pattern": "^[0-9]{1,19}$",
            "description": "Smaller deposits are recorded and need attention; they are not credited"
          },
          "confirmation": {
            "type": "string"
          },
          "warnings": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "assets": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DepositAsset"
            }
          }
        }
      },
      "GramDeposit": {
        "type": "object",
        "required": [
          "object",
          "id",
          "status",
          "asset",
          "amount_nanogram",
          "network",
          "tx_hash",
          "explorer_url",
          "sender_masked",
          "observed_at",
          "credited_at",
          "hold_reason"
        ],
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "gram_deposit"
            ]
          },
          "id": {
            "type": "string",
            "pattern": "^dep_[0-9A-HJKMNP-TV-Z]{26}$"
          },
          "status": {
            "type": "string",
            "enum": [
              "confirming",
              "credited",
              "on_hold",
              "needs_attention"
            ],
            "description": "confirming: seen, not yet finalised and confirmed by two sources; on_hold: received and held for review, not yet credited and not on your balance: it cannot be spent, shows only in pending_nanogram, and becomes credited on release; needs_attention: not native GRAM, below the minimum, or sources disagree. Tolerate new values"
          },
          "asset": {
            "type": "string",
            "enum": [
              "GRAM"
            ]
          },
          "amount_nanogram": {
            "type": "string",
            "pattern": "^[0-9]{1,19}$"
          },
          "network": {
            "type": "string",
            "enum": [
              "TON",
              "TON testnet",
              "simulated"
            ]
          },
          "tx_hash": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$"
          },
          "explorer_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "sender_masked": {
            "type": "string"
          },
          "observed_at": {
            "type": "string",
            "format": "date-time"
          },
          "credited_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "hold_reason": {
            "type": [
              "string",
              "null"
            ]
          },
          "conversion": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/GramConversion"
              },
              {
                "type": "null"
              }
            ],
            "description": "Set once this deposit has become USD credits"
          }
        }
      },
      "StatementCreate": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "from",
          "to"
        ],
        "properties": {
          "from": {
            "type": "string",
            "format": "date"
          },
          "to": {
            "type": "string",
            "format": "date"
          },
          "formats": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "csv",
                "pdf"
              ]
            },
            "minItems": 1,
            "maxItems": 2,
            "uniqueItems": true,
            "contains": {
              "const": "csv"
            }
          }
        }
      },
      "StatementBalances": {
        "type": "object",
        "required": [
          "available",
          "reserved",
          "on_hold",
          "total"
        ],
        "description": "Micro-dollars as integer strings. Total is available plus reserved, never on hold.",
        "properties": {
          "available": {
            "type": "string",
            "pattern": "^-?[0-9]{1,30}$"
          },
          "reserved": {
            "type": "string",
            "pattern": "^-?[0-9]{1,30}$"
          },
          "on_hold": {
            "type": "string",
            "pattern": "^-?[0-9]{1,30}$"
          },
          "total": {
            "type": "string",
            "pattern": "^-?[0-9]{1,30}$"
          }
        }
      },
      "Statement": {
        "type": "object",
        "description": "An account statement. `reconciled` is true only once ready; `summary` is null until then. A released reservation is \"Reservation returned\", never a refund.",
        "required": [
          "id",
          "state",
          "failure_code",
          "currency",
          "timezone",
          "reconciled",
          "period",
          "formats",
          "movement_count",
          "created_at",
          "finished_at",
          "files",
          "summary"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^stm_[0-9A-HJKMNP-TV-Z]{26}$"
          },
          "state": {
            "type": "string",
            "enum": [
              "queued",
              "ready",
              "failed"
            ]
          },
          "failure_code": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "reconciliation_failed",
              "too_large",
              null
            ]
          },
          "currency": {
            "type": "string",
            "enum": [
              "USD"
            ]
          },
          "timezone": {
            "type": "string"
          },
          "reconciled": {
            "type": "boolean"
          },
          "period": {
            "type": "object",
            "required": [
              "from",
              "to",
              "from_at",
              "to_at"
            ],
            "properties": {
              "from": {
                "type": "string",
                "format": "date"
              },
              "to": {
                "type": "string",
                "format": "date"
              },
              "from_at": {
                "type": "string",
                "format": "date-time"
              },
              "to_at": {
                "type": "string",
                "format": "date-time"
              }
            }
          },
          "formats": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "csv",
                "pdf"
              ]
            }
          },
          "movement_count": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 0
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "finished_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "files": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "format",
                "byte_size",
                "sha256",
                "expires_at",
                "available"
              ],
              "properties": {
                "format": {
                  "type": "string",
                  "enum": [
                    "csv",
                    "pdf"
                  ]
                },
                "byte_size": {
                  "type": "integer",
                  "minimum": 1
                },
                "sha256": {
                  "type": "string",
                  "pattern": "^[0-9a-f]{64}$"
                },
                "expires_at": {
                  "type": "string",
                  "format": "date-time"
                },
                "available": {
                  "type": "boolean"
                }
              }
            }
          },
          "summary": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "type": "object",
                "required": [
                  "opening",
                  "closing",
                  "categories",
                  "spent",
                  "orders_charged",
                  "deposits_credited",
                  "reservations_returned",
                  "refunded",
                  "adjustments",
                  "spent_by_product"
                ],
                "properties": {
                  "opening": {
                    "$ref": "#/components/schemas/StatementBalances"
                  },
                  "closing": {
                    "$ref": "#/components/schemas/StatementBalances"
                  },
                  "categories": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "required": [
                        "category",
                        "label",
                        "count",
                        "change"
                      ],
                      "properties": {
                        "category": {
                          "type": "string"
                        },
                        "label": {
                          "type": "string"
                        },
                        "count": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "change": {
                          "$ref": "#/components/schemas/StatementBalances"
                        }
                      }
                    }
                  },
                  "spent": {
                    "type": "string",
                    "pattern": "^-?[0-9]{1,30}$"
                  },
                  "orders_charged": {
                    "type": "integer",
                    "minimum": 0
                  },
                  "deposits_credited": {
                    "type": "string",
                    "pattern": "^-?[0-9]{1,30}$"
                  },
                  "reservations_returned": {
                    "type": "string",
                    "pattern": "^-?[0-9]{1,30}$"
                  },
                  "refunded": {
                    "type": "string",
                    "pattern": "^-?[0-9]{1,30}$"
                  },
                  "adjustments": {
                    "type": "string",
                    "pattern": "^-?[0-9]{1,30}$"
                  },
                  "spent_by_product": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "required": [
                        "product",
                        "spent",
                        "count"
                      ],
                      "properties": {
                        "product": {
                          "type": "string"
                        },
                        "spent": {
                          "type": "string",
                          "pattern": "^-?[0-9]{1,30}$"
                        },
                        "count": {
                          "type": "integer",
                          "minimum": 1
                        }
                      }
                    }
                  }
                }
              }
            ]
          }
        }
      },
      "StatementList": {
        "type": "object",
        "required": [
          "data",
          "has_more",
          "next_cursor"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Statement"
            }
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "Limits": {
        "type": "object",
        "required": [
          "as_of",
          "timezone",
          "enforcement",
          "period",
          "used",
          "platform",
          "rules"
        ],
        "properties": {
          "as_of": {
            "type": "string",
            "format": "date-time"
          },
          "timezone": {
            "type": "string",
            "description": "The zone the workspace's own limits count days and months in"
          },
          "enforcement": {
            "type": "object",
            "required": [
              "block",
              "notify"
            ],
            "properties": {
              "block": {
                "type": "boolean"
              },
              "notify": {
                "type": "boolean"
              }
            }
          },
          "period": {
            "type": "object",
            "required": [
              "day_start",
              "day_end",
              "month_start",
              "month_end"
            ],
            "properties": {
              "day_start": {
                "type": "string",
                "format": "date-time"
              },
              "day_end": {
                "type": "string",
                "format": "date-time"
              },
              "month_start": {
                "type": "string",
                "format": "date-time"
              },
              "month_end": {
                "type": "string",
                "format": "date-time"
              }
            }
          },
          "used": {
            "type": "object",
            "required": [
              "today_micros",
              "this_month_micros"
            ],
            "properties": {
              "today_micros": {
                "$ref": "#/components/schemas/UsdMicros"
              },
              "this_month_micros": {
                "$ref": "#/components/schemas/UsdMicros"
              }
            }
          },
          "platform": {
            "type": "object",
            "required": [
              "per_order_micros",
              "daily_micros",
              "used_today_micros",
              "timezone",
              "resets_at"
            ],
            "properties": {
              "per_order_micros": {
                "$ref": "#/components/schemas/UsdMicros"
              },
              "daily_micros": {
                "$ref": "#/components/schemas/UsdMicros"
              },
              "used_today_micros": {
                "$ref": "#/components/schemas/UsdMicros"
              },
              "timezone": {
                "type": "string",
                "enum": [
                  "Africa/Lagos"
                ]
              },
              "resets_at": {
                "type": "string",
                "format": "date-time"
              }
            }
          },
          "rules": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SpendingLimit"
            }
          }
        }
      },
      "SpendingLimit": {
        "type": "object",
        "required": [
          "id",
          "version",
          "mode",
          "window",
          "product",
          "amount_micros",
          "enforced",
          "used_micros",
          "resets_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^lim_[0-9A-HJKMNP-TV-Z]{26}$"
          },
          "version": {
            "type": "integer",
            "minimum": 1
          },
          "mode": {
            "type": "string",
            "enum": [
              "block",
              "notify"
            ]
          },
          "window": {
            "type": "string",
            "enum": [
              "order",
              "day",
              "month"
            ]
          },
          "product": {
            "type": [
              "string",
              "null"
            ],
            "description": "The product it limits, or null for every product"
          },
          "amount_micros": {
            "$ref": "#/components/schemas/UsdMicros"
          },
          "enforced": {
            "type": "boolean"
          },
          "used_micros": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/UsdMicros"
              },
              {
                "type": "null"
              }
            ],
            "description": "Null for a per-order limit"
          },
          "resets_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        }
      },
      "UsdMicros": {
        "type": "string",
        "pattern": "^(0|[1-9][0-9]{0,15})$",
        "description": "An integer number of micro-dollars (1 USD = 1,000,000), as a string. Every price is a whole number of cents"
      },
      "SpendingCurrency": {
        "type": "string",
        "enum": [
          "USD",
          "TON"
        ],
        "description": "What the organisation's orders are paid from. USD: USD credits, the balance every deposit converts into. TON: GRAM. It moves one way only, to USD, and never back."
      },
      "UsdBalance": {
        "type": "object",
        "description": "USD credits, the spending balance of a USD organisation (ledger currency USD, in micro-dollars): stored obligations, never revalued. GRAM is credited here at the verified rate less the deposit spread when it is credited. These figures are the ledger's and never change with the display currency.",
        "required": [
          "currency",
          "available_micros",
          "held_micros",
          "pending_micros",
          "available",
          "held",
          "pending",
          "rounded"
        ],
        "properties": {
          "currency": {
            "type": "string",
            "enum": [
              "USD"
            ]
          },
          "available_micros": {
            "$ref": "#/components/schemas/UsdMicros"
          },
          "held_micros": {
            "allOf": [
              {
                "$ref": "#/components/schemas/UsdMicros"
              }
            ],
            "description": "Reserved for orders in progress"
          },
          "pending_micros": {
            "allOf": [
              {
                "$ref": "#/components/schemas/UsdMicros"
              }
            ],
            "description": "Received and held for review, not yet credited and not on your balance: it cannot be spent, and becomes credited on release"
          },
          "available": {
            "type": "string",
            "pattern": "^[0-9]+\\.[0-9]{2}$",
            "description": "USD, rounded down to the cent: never more than is spendable"
          },
          "held": {
            "type": "string",
            "pattern": "^[0-9]+\\.[0-9]{2}$"
          },
          "pending": {
            "type": "string",
            "pattern": "^[0-9]+\\.[0-9]{2}$"
          },
          "rounded": {
            "type": "string",
            "enum": [
              "down"
            ]
          }
        }
      },
      "EstimatedUsd": {
        "type": "object",
        "description": "An indicative value in USD of a GRAM amount, at the newest good GRAM/USD rate (GET /v1/rates). An estimate, never a balance: GRAM stays GRAM. Null figures when no good rate is recent enough.",
        "required": [
          "available",
          "amount_micros",
          "amount",
          "usd_per_gram",
          "rate_time"
        ],
        "properties": {
          "available": {
            "type": "boolean"
          },
          "amount_micros": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/UsdMicros"
              },
              {
                "type": "null"
              }
            ],
            "description": "Rounded down"
          },
          "amount": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^[0-9]+\\.[0-9]{2}$",
            "description": "USD, rounded down to the cent"
          },
          "usd_per_gram": {
            "type": [
              "string",
              "null"
            ]
          },
          "rate_time": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        }
      },
      "BalancePart": {
        "type": "object",
        "required": [
          "asset",
          "amount_micros",
          "is_estimate"
        ],
        "properties": {
          "asset": {
            "type": "string",
            "enum": [
              "USD",
              "GRAM"
            ],
            "description": "USD credits (fixed, the ledger figure) or GRAM at its estimate"
          },
          "amount_micros": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/UsdMicros"
              },
              {
                "type": "null"
              }
            ],
            "description": "Null for GRAM with no good rate"
          },
          "is_estimate": {
            "type": "boolean"
          }
        }
      },
      "BalanceHeadline": {
        "type": "object",
        "description": "The one figure to show first. For a USD organisation it is its spendable USD credits, fixed. For an organisation that still spends GRAM it is the estimated value of its GRAM: is_estimate is then true, so show it with a ≈, and complete is false when no good rate exists, so the figure is 0.",
        "required": [
          "currency",
          "amount_micros",
          "amount",
          "is_estimate",
          "complete",
          "composition"
        ],
        "properties": {
          "currency": {
            "type": "string",
            "enum": [
              "USD"
            ]
          },
          "amount_micros": {
            "$ref": "#/components/schemas/UsdMicros"
          },
          "amount": {
            "type": "string",
            "pattern": "^[0-9]+\\.[0-9]{2}$",
            "description": "USD, rounded down to the cent"
          },
          "is_estimate": {
            "type": "boolean"
          },
          "complete": {
            "type": "boolean"
          },
          "composition": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BalancePart"
            }
          }
        }
      },
      "UsageDeduction": {
        "type": "object",
        "description": "One order's charge against a balance, as the ledger holds it",
        "required": [
          "order_id",
          "state",
          "currency",
          "amount_minor",
          "at"
        ],
        "properties": {
          "order_id": {
            "type": "string",
            "pattern": "^ord_[0-9A-HJKMNP-TV-Z]{26}$"
          },
          "state": {
            "type": "string",
            "enum": [
              "reserved",
              "charged",
              "returned"
            ],
            "description": "reserved: held for an order in progress; charged: delivered; returned: not delivered, given back"
          },
          "currency": {
            "type": "string",
            "enum": [
              "USD",
              "TON"
            ],
            "description": "USD in micro-dollars, or TON (GRAM) in nanogram"
          },
          "amount_minor": {
            "type": "string",
            "pattern": "^[1-9][0-9]{0,18}$"
          },
          "at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "BalanceActivity": {
        "type": "object",
        "description": "The newest deposits (at most 5) and the newest order charges (at most 5), as recorded. Never recalculated usage is left out for a caller who may not read orders, and deposits is empty for one who may not read transactions.",
        "required": [
          "deposits"
        ],
        "properties": {
          "deposits": {
            "type": "array",
            "maxItems": 5,
            "items": {
              "$ref": "#/components/schemas/Deposit"
            }
          },
          "usage": {
            "type": "array",
            "maxItems": 5,
            "items": {
              "$ref": "#/components/schemas/UsageDeduction"
            }
          }
        }
      },
      "UsdSettlement": {
        "type": "object",
        "description": "Present when an order is paid from USD credits. What it charges, exactly, with no rate and no conversion: `amount_usd_micros` is the charge, the breakdown's total (product line and every fee), and is what the order reserves. The quote's and order's `amount` is the product line's price alone; read the charge here, never from `amount`.",
        "required": [
          "currency",
          "amount_usd_micros",
          "amount_usd",
          "price_usd_micros",
          "price_book_version"
        ],
        "properties": {
          "currency": {
            "type": "string",
            "enum": [
              "USD"
            ]
          },
          "amount_usd_micros": {
            "$ref": "#/components/schemas/UsdMicros"
          },
          "amount_usd": {
            "type": "string",
            "pattern": "^[0-9]+\\.[0-9]{6}$"
          },
          "price_usd_micros": {
            "type": "string",
            "pattern": "^[1-9][0-9]{0,12}$"
          },
          "price_book_version": {
            "type": "integer",
            "minimum": 1
          }
        }
      },
      "BreakdownLine": {
        "type": "object",
        "required": [
          "kind",
          "amount_usd_micros"
        ],
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "product",
              "service_fee",
              "network_fee"
            ],
            "description": "network_fee is paid by Nasfam and is 0"
          },
          "amount_usd_micros": {
            "$ref": "#/components/schemas/UsdMicros"
          }
        }
      },
      "QuotePayment": {
        "type": "object",
        "description": "What the order will charge from the USD balance, fixed by the quote. The projection is the balance at quote time less the amount; the order's reservation gives the real balance after. A negative projection means the order would be refused for insufficient funds.",
        "required": [
          "pay_with",
          "balance",
          "currency",
          "amount_minor",
          "balance_before_minor",
          "balance_after_projected_minor",
          "projected"
        ],
        "properties": {
          "pay_with": {
            "type": "string",
            "enum": [
              "auto",
              "usd"
            ],
            "description": "What was asked"
          },
          "balance": {
            "type": "string",
            "enum": [
              "usd"
            ]
          },
          "currency": {
            "type": "string",
            "enum": [
              "USD"
            ],
            "description": "Micro-dollars"
          },
          "amount_minor": {
            "type": "string",
            "pattern": "^[1-9][0-9]{0,18}$"
          },
          "balance_before_minor": {
            "type": "string",
            "pattern": "^(0|[1-9][0-9]{0,18})$"
          },
          "balance_after_projected_minor": {
            "type": "string",
            "pattern": "^-?(0|[1-9][0-9]{0,18})$"
          },
          "projected": {
            "type": "boolean",
            "enum": [
              true
            ]
          }
        }
      },
      "DepositAsset": {
        "type": "object",
        "description": "One asset this address receives.",
        "required": [
          "asset",
          "available",
          "minimum_minor",
          "unit",
          "credit_rule"
        ],
        "properties": {
          "asset": {
            "type": "string",
            "enum": [
              "GRAM"
            ]
          },
          "available": {
            "type": "boolean",
            "description": "false: do not send this asset here yet; it is not credited"
          },
          "minimum_minor": {
            "type": "string",
            "pattern": "^[0-9]{1,19}$",
            "description": "nanogram for GRAM"
          },
          "unit": {
            "type": "string",
            "enum": [
              "nanogram"
            ]
          },
          "credit_rule": {
            "type": "string"
          }
        }
      },
      "GramConversion": {
        "type": "object",
        "description": "How a GRAM deposit became USD credits, as recorded when it was credited. An immutable snapshot, never recalculated.",
        "required": [
          "rate",
          "spread_bps",
          "rate_applied",
          "credited_usd_micros",
          "converted_at",
          "policy_version"
        ],
        "properties": {
          "rate": {
            "type": "object",
            "required": [
              "usd_per_gram",
              "usd_micros_per_gram",
              "source_time"
            ],
            "properties": {
              "usd_per_gram": {
                "type": "string"
              },
              "usd_micros_per_gram": {
                "$ref": "#/components/schemas/Fraction"
              },
              "source_time": {
                "type": "string",
                "format": "date-time"
              }
            }
          },
          "spread_bps": {
            "type": "integer",
            "minimum": 0,
            "description": "The deposit spread, in basis points"
          },
          "rate_applied": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Fraction"
              }
            ],
            "description": "USD micros per GRAM after the spread"
          },
          "credited_usd_micros": {
            "$ref": "#/components/schemas/UsdMicros"
          },
          "converted_at": {
            "type": "string",
            "format": "date-time"
          },
          "policy_version": {
            "type": "integer",
            "minimum": 1
          }
        }
      },
      "Deposit": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/GramDeposit"
          }
        ]
      },
      "EventType": {
        "type": "string",
        "enum": [
          "order.accepted",
          "order.processing",
          "order.succeeded",
          "order.failed",
          "order.refunded",
          "order.under_review",
          "funding.credited",
          "deposit.confirmed",
          "balance.low",
          "balance.recovered"
        ]
      },
      "Event": {
        "type": "object",
        "required": [
          "id",
          "type",
          "timestamp",
          "environment",
          "api_version",
          "data"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^evt_[0-9A-HJKMNP-TV-Z]{26}$"
          },
          "type": {
            "$ref": "#/components/schemas/EventType"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "environment": {
            "type": "string",
            "enum": [
              "live",
              "sandbox"
            ]
          },
          "api_version": {
            "const": "v1"
          },
          "data": {
            "type": "object",
            "required": [
              "object"
            ],
            "properties": {
              "object": {
                "type": "object",
                "description": "A full snapshot of the subject: the order for an order.* event, as GET /orders/{id} presents it; the funding for funding.credited, as GET /fundings presents it; the deposit for deposit.confirmed, as GET /funding/deposits presents it, so its status reads confirming until it is booked; for balance.low and balance.recovered only alert_id, state (firing or recovered) and at, never an amount, a threshold or a balance: read GET /v1/balance for the figures. A balance event is sent only to an organisation that chose the webhook channel for its low-balance alert."
              }
            }
          },
          "test": {
            "const": true,
            "description": "Present only on a test event (sendWebhookTestEvent), whose object is synthetic: never act on it as a real order or funding"
          }
        }
      },
      "WebhookTestEventCreate": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "type"
        ],
        "properties": {
          "type": {
            "$ref": "#/components/schemas/EventType"
          }
        }
      },
      "WebhookEndpointCreate": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "url",
          "events"
        ],
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "pattern": "^https://",
            "maxLength": 2048
          },
          "events": {
            "type": "array",
            "minItems": 1,
            "uniqueItems": true,
            "items": {
              "$ref": "#/components/schemas/EventType"
            }
          },
          "description": {
            "type": "string",
            "maxLength": 200,
            "pattern": "^[^\\u0000\\uD800-\\uDFFF]*$"
          }
        }
      },
      "WebhookEndpointUpdate": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "pattern": "^https://",
            "maxLength": 2048
          },
          "events": {
            "type": "array",
            "minItems": 1,
            "uniqueItems": true,
            "items": {
              "$ref": "#/components/schemas/EventType"
            }
          },
          "description": {
            "type": "string",
            "maxLength": 200,
            "pattern": "^[^\\u0000\\uD800-\\uDFFF]*$"
          },
          "enabled": {
            "type": "boolean"
          }
        }
      },
      "WebhookEndpoint": {
        "type": "object",
        "required": [
          "id",
          "url",
          "events",
          "enabled",
          "created_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^whe_[0-9A-HJKMNP-TV-Z]{26}$"
          },
          "url": {
            "type": "string"
          },
          "events": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EventType"
            }
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "enabled": {
            "type": "boolean"
          },
          "disabled_reason": {
            "type": [
              "string",
              "null"
            ],
            "examples": [
              "repeated_failures",
              "gone_410"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "WebhookEndpointWithSecret": {
        "allOf": [
          {
            "$ref": "#/components/schemas/WebhookEndpoint"
          },
          {
            "type": "object",
            "required": [
              "secret"
            ],
            "properties": {
              "secret": {
                "type": "string",
                "pattern": "^whsec_[A-Za-z0-9+/=]{43,88}$",
                "description": "Shown once."
              }
            }
          }
        ]
      },
      "WebhookEndpointRotation": {
        "allOf": [
          {
            "$ref": "#/components/schemas/WebhookEndpoint"
          },
          {
            "type": "object",
            "properties": {
              "secret": {
                "type": "string",
                "pattern": "^whsec_[A-Za-z0-9+/=]{43,88}$",
                "description": "The new secret, shown once. Absent from a replay (Idempotent-Replayed: true)."
              }
            }
          }
        ]
      },
      "WebhookDelivery": {
        "type": "object",
        "required": [
          "id",
          "event_id",
          "attempt",
          "status",
          "created_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^whd_[0-9A-HJKMNP-TV-Z]{26}$"
          },
          "event_id": {
            "type": "string"
          },
          "attempt": {
            "type": "integer",
            "minimum": 1
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "succeeded",
              "failed",
              "abandoned"
            ]
          },
          "response_status": {
            "type": [
              "integer",
              "null"
            ]
          },
          "duration_ms": {
            "type": [
              "integer",
              "null"
            ]
          },
          "failure_class": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/WebhookFailureClass"
              },
              {
                "type": "null"
              }
            ],
            "description": "Null when accepted (2xx) or not yet attempted, and for a stored answer with no class (a 101 recorded before such answers were recorded as connection failures)."
          },
          "next_attempt_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "WebhookFailureClass": {
        "type": "string",
        "enum": [
          "dns_unresolvable",
          "url_refused",
          "connection_failed",
          "tls_failed",
          "timeout",
          "redirect",
          "auth_rejected",
          "not_found",
          "gone",
          "rate_limited",
          "client_error",
          "server_error"
        ],
        "description": "Why an attempt was not accepted. `timeout` and `connection_failed` mean the event may have arrived. Never an address, a body or a header."
      },
      "Account": {
        "type": "object",
        "required": [
          "id",
          "name",
          "environment",
          "kyb_status",
          "limits"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^org_[0-9A-HJKMNP-TV-Z]{26}$"
          },
          "name": {
            "type": "string"
          },
          "environment": {
            "type": "string",
            "enum": [
              "live",
              "sandbox"
            ]
          },
          "kyb_status": {
            "type": "string",
            "enum": [
              "sandbox_only",
              "draft",
              "submitted",
              "in_review",
              "needs_info",
              "verified",
              "rejected",
              "active",
              "restricted",
              "suspended",
              "closed"
            ],
            "description": "In the sandbox, `sandbox_only` for an organisation in good standing: no KYB is recorded there. In Live, the activation state, `active` once the organisation is activated. `restricted`, `suspended` and `closed` in either."
          },
          "limits": {
            "type": "object",
            "required": [
              "max_queued"
            ],
            "description": "The limits the server keeps for this organisation. Rate limits are not here; each response's RateLimit-Policy header states the buckets it drew on.",
            "properties": {
              "max_queued": {
                "type": "integer",
                "minimum": 1,
                "maximum": 1000,
                "description": "The most orders that may be processing at once; an order beyond it is 429 queue_limit"
              }
            }
          }
        }
      },
      "ProblemCategory": {
        "type": "string",
        "enum": [
          "authentication",
          "authorisation",
          "validation",
          "balance",
          "rate_limit",
          "provider",
          "webhook",
          "internal",
          "timeout",
          "unknown_outcome"
        ],
        "description": "What kind of problem a code is, fixed per code (x-nb-problem-codes), except that internal_error on an operation that moves money is unknown_outcome: the request may have been accepted, so retry with the same Idempotency-Key, which never repeats it."
      },
      "Problem": {
        "type": "object",
        "required": [
          "type",
          "title",
          "status",
          "code",
          "category",
          "request_id"
        ],
        "properties": {
          "type": {
            "type": "string",
            "format": "uri",
            "description": "The address of the code's entry on the documentation's errors page (errors#<code>): its explanation and fix."
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "integer"
          },
          "category": {
            "$ref": "#/components/schemas/ProblemCategory"
          },
          "code": {
            "type": "string",
            "examples": [
              "invalid_request",
              "unknown_field",
              "insufficient_scope",
              "key_environment_mismatch",
              "insufficient_funds",
              "quote_expired",
              "quote_already_used",
              "price_changed",
              "duplicate_reference",
              "idempotency_key_reused",
              "idempotency_in_progress",
              "queue_limit",
              "rate_limited",
              "account_restricted",
              "capacity_exhausted",
              "pricing_unavailable",
              "product_unavailable",
              "recipient_not_found",
              "recipient_not_eligible",
              "not_found",
              "invalid_api_key",
              "key_expired",
              "idempotency_key_required",
              "payload_too_large",
              "unsupported_media_type",
              "browser_request_refused",
              "webhook_url_refused",
              "endpoint_limit",
              "service_unavailable",
              "internal_error",
              "order_limit_exceeded",
              "provider_unavailable",
              "lookup_expired",
              "recipient_mismatch",
              "recipient_lookup_required",
              "product_not_permitted",
              "spending_limit_reached",
              "statement_not_ready",
              "ip_not_allowed"
            ]
          },
          "detail": {
            "type": "string"
          },
          "param": {
            "type": [
              "string",
              "null"
            ]
          },
          "request_id": {
            "type": "string"
          },
          "limit": {
            "$ref": "#/components/schemas/SpendingLimitRefusal"
          }
        }
      },
      "SpendingLimitRefusal": {
        "type": "object",
        "required": [
          "id",
          "window",
          "product",
          "resets_at"
        ],
        "description": "On `spending_limit_reached` (422) only, and only for a key holding `limits:read`: the workspace rule that refused the order (the one with the least headroom). Never an amount or a headroom. A workspace limit is distinct from the platform limit, `order_limit_exceeded`. Additive.",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^lim_[0-9A-HJKMNP-TV-Z]{26}$"
          },
          "window": {
            "type": "string",
            "enum": [
              "order",
              "day",
              "month"
            ]
          },
          "product": {
            "type": [
              "string",
              "null"
            ],
            "description": "The product the rule limits, or null for every product."
          },
          "resets_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "The next local midnight (day) or first of the next month (month) in the workspace zone; null for a per-order rule."
          }
        }
      }
    }
  }
}
