openapi: 3.1.2
info:
  title: Nbta Gateway API
  version: 1.0.0
  description: |
    Server-to-server API for the owner-operated Nbta payment gateway.
    Monetary values are decimal strings or atomic-integer strings, never JSON numbers.

    ## Payment attribution

    Every invoice has a unique payable amount on its receiving wallet. A
    finalized transfer settles an invoice under these rules:

    - **Exact amount.** A transfer of exactly `payable_amount_atomic` settles
      the invoice that owns that amount.
    - **More than the amount.** A transfer above the payable amount settles an
      invoice automatically when it can be attributed to exactly one open
      invoice on that wallet, and only up to `max(1 token, 5%)` above the
      payable amount, with the 5% rounded down to a whole atomic unit
      (`accepted_max_amount_atomic` on the public checkout). When another
      invoice open at block time is within its own band of the transfer,
      above or below it, the transfer stays unmatched. It settles later once
      every competitor priced at or below it is paid by its own transfer; a
      competitor priced above it keeps it unmatched, because it may be that
      payer's short first attempt. The excess is reported as
      `overpaid_amount_atomic`.
    - **Less than the amount.** A transfer below the payable amount never
      settles an invoice.

    Settled invoices expose `received_amount_atomic` and
    `overpaid_amount_atomic`, and the `invoice.paid` and `invoice.late_paid`
    webhooks carry both values.

    ## Return to store and customer

    `success_url` and `cancel_url` are optional absolute `https` URLs (at most
    2048 characters; test keys may also use `http` on `localhost`,
    `127.0.0.1` or `[::1]`). The hosted checkout offers `success_url` once the
    invoice is `paid` or `late_paid` and `cancel_url` while it is not.

    `customer` is an optional `{email, name}` object with at least one of the
    two. It is returned on your invoice objects and in `invoice.paid` and
    `invoice.late_paid` webhooks as `data.invoice.customer` (null when not
    sent). The public checkout never shows it. Sandbox events (test keys) keep
    their own flat shape and carry it as `data.customer`.

    ## Payer receipt email

    When the owner turns on payer receipts for the project (dashboard project
    panel, or `payer_receipts_enabled` on `PATCH /v1/account/projects/{id}`),
    each `paid` or `late_paid` invoice that carries `customer.email` sends the
    payer one Arabic and English receipt from `no-reply@sbarah.com`. The email
    is used only for that receipt; the public checkout never shows it and
    reports only `receipt_email: true` or `false`. The receipt is a courtesy
    for the payer: the signed `invoice.paid` (or `invoice.late_paid`) webhook
    stays the only signal to fulfil an order.

    Return URLs, the customer name and the customer email must not contain
    bidirectional overrides or zero width characters (U+200B to U+200F,
    U+202A to U+202E, U+2066 to U+2069, U+FEFF); such requests get a 422.

    ```json
    {
      "external_id": "order-1042",
      "amount": "25.00",
      "payment_route_id": "6f1c2a4e-8b3d-4c5e-9a7f-0d2e4b6c8a10",
      "success_url": "https://store.example/orders/1042/thanks",
      "cancel_url": "https://store.example/cart",
      "customer": { "email": "sara@example.com", "name": "Sara Ali" },
      "metadata": { "cart_id": "c_8812" }
    }
    ```

    ## Owner notifications

    An owner can link one or more Telegram chats to the account from the
    dashboard (a 15 minute, single-use code opened in the Nbta bot). Each
    `paid` or `late_paid` invoice then sends one short Arabic and English
    message per enabled chat with the project, amount received, any excess,
    the customer when present and `external_id`. Notifications are
    independent of webhooks and never delay or change them.

    ## Webhook delivery

    Delivery is at least once and not ordered. The same event can arrive more
    than once and events can arrive out of order, so store each `webhook-id`
    you have handled and ignore repeats.

    When an endpoint answers `410 Gone` it is disabled. The event that got the
    410 and the project's other pending events are held, not retried, for 7
    days. Saving a new endpoint with
    `POST /v1/account/projects/{project_id}/webhooks` releases the held events
    and they are sent again in their original order. Events still held after 7
    days expire and are not sent. No event row is deleted and the
    invoice itself is unchanged: read it with `GET /v1/invoices/{invoice_id}`
    to recover the state of an event that expired.

    ## Rate limits

    A refused request answers `429` with `code: rate_limited` and a
    `Retry-After` header in seconds. The public checkout status
    (`GET /public/invoices/{public_id}`) is limited per client address (120
    requests a minute) and, as a second ceiling, per invoice (1200 requests a
    minute), so one holder of a checkout link cannot lock out the others.

    ## Project key lifecycle

    A project API key records the member who created it. When that member is
    removed from the account or demoted, the keys they created are revoked,
    including keys created through an account agent key they made. Keys that
    were created before this was recorded are not revoked automatically.

    ## Integrate with an AI agent

    The owner creates an account agent key (`nbta_acct_live_...`) once in the
    dashboard and hands it to an AI agent working in the store's repository.
    The agent calls `POST /v1/account/setup` with the project name, site URL,
    webhook URL and networks. One call creates or reuses the project (by
    slug), attaches the owner's wallet per network, issues a project API key
    and sets the webhook endpoint. The response carries the project API key
    and webhook signing secret once, plus a ready `.env` block with
    `NBTA_API_URL`, `NBTA_API_KEY` and `NBTA_WEBHOOK_SECRET`.

    When a network has no wallet or several, setup changes nothing and answers
    `409 wallet_selection_required` with `selections[].choices`; repeat the call
    with `wallet_ids`. The project key and webhook secret are shown only on the
    call that creates them, so store them on the first setup. Repeating setup
    returns `key_created: false` and only the key prefix, and
    `webhook.changed: false` without a secret when the URL is unchanged; pass
    `rotate_key` when the key is lost and `rotate_webhook` to replace the
    signing secret. `PUT /v1/account/projects/{project_id}/wallets` is atomic:
    all entries apply or none.

    Account keys only call `/v1/account/*`; project keys only call the project
    endpoints. Account calls are limited per key to 120 reads and 30 writes a
    minute. Every change is audited with the key id and sends a Telegram
    security alert to the owner.
  license:
    name: Proprietary
    identifier: LicenseRef-Proprietary
servers:
  - url: https://nbta.sbarah.com/api
    description: Production
tags:
  - name: Health
    description: Process liveness without dependency or secret disclosure.
  - name: Payment routes
    description: Project-scoped, allowlisted payment routes.
  - name: Invoices
    description: Idempotent invoice lifecycle operations.
  - name: Sandbox
    description: |
      Isolated fake-money scenarios available only to test API keys. A sandbox
      invoice has a `public_id` of the form `sandbox_<32 hex>`, not `pub_...`.
      The public checkout endpoint serves `pub_` ids only, so read a sandbox
      invoice's status with `GET /v1/invoices/{invoice_id}` and your test key.
  - name: Public checkout
    description: Minimal unauthenticated projection for hosted checkout.
  - name: Webhooks
    description: Signed events delivered to the project's webhook endpoint.
  - name: Account
    description: |
      Account management for AI agents, authenticated by an account agent key.
      Create projects, attach wallets, issue project keys and webhooks.
security:
  - ProjectKey: []
paths:
  /v1/health:
    get:
      operationId: gatewayHealth
      tags: [Health]
      security: []
      summary: Read the gateway liveness state
      responses:
        "200":
          description: Gateway process is reachable.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Health"
        "404":
          $ref: "#/components/responses/Problem"
        "503":
          $ref: "#/components/responses/Problem"
  /v1/payment-routes:
    get:
      operationId: listPaymentRoutes
      tags: [Payment routes]
      summary: List enabled routes for the authenticated project
      responses:
        "200":
          description: Enabled routes.
          headers:
            X-RateLimit-Limit:
              $ref: "#/components/headers/RateLimitLimit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/RateLimitRemaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/RateLimitReset"
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required: [data]
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/PaymentRoute"
        "401":
          $ref: "#/components/responses/Problem"
        "403":
          $ref: "#/components/responses/Problem"
        "429":
          $ref: "#/components/responses/RateLimited"
        "503":
          $ref: "#/components/responses/Problem"
  /v1/invoices:
    get:
      operationId: listInvoices
      tags: [Invoices]
      summary: List project invoices using an opaque signed cursor
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
        - name: after
          in: query
          schema:
            type: string
            minLength: 20
        - name: status
          in: query
          schema:
            $ref: "#/components/schemas/InvoiceStatus"
      responses:
        "200":
          description: Invoice page.
          headers:
            X-RateLimit-Limit:
              $ref: "#/components/headers/RateLimitLimit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/RateLimitRemaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/RateLimitReset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InvoicePage"
        "401":
          $ref: "#/components/responses/Problem"
        "403":
          $ref: "#/components/responses/Problem"
        "422":
          $ref: "#/components/responses/Problem"
        "429":
          $ref: "#/components/responses/RateLimited"
        "503":
          $ref: "#/components/responses/Problem"
    post:
      operationId: createInvoice
      tags: [Invoices]
      summary: Create an invoice with an exact-amount reservation
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateInvoiceRequest"
            examples:
              returnUrlsAndCustomer:
                summary: Invoice with return URLs, customer and metadata
                value:
                  external_id: order-1042
                  amount: "25.00"
                  payment_route_id: 6f1c2a4e-8b3d-4c5e-9a7f-0d2e4b6c8a10
                  success_url: https://store.example/orders/1042/thanks
                  cancel_url: https://store.example/cart
                  customer:
                    email: sara@example.com
                    name: Sara Ali
                  metadata:
                    cart_id: c_8812
      responses:
        "201":
          description: Invoice created or the original idempotent response returned.
          headers:
            Location:
              schema:
                type: string
            X-RateLimit-Limit:
              $ref: "#/components/headers/RateLimitLimit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/RateLimitRemaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/RateLimitReset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreatedInvoice"
              examples:
                created:
                  summary: Created live invoice
                  value:
                    id: 3f8e2b1c-5d7a-4e9b-8c6d-1a2b3c4d5e6f
                    public_id: pub_9b1f4c7e2a8d4f6b0c3e5a7d9f1b2c4e
                    external_id: order-1042
                    status: pending
                    asset:
                      route: bsc_usd_bep20
                      display_name: Binance-Peg BSC-USD
                      network: bsc_mainnet
                      network_standard: BEP-20
                      chain_id: "56"
                      contract: "0x55d398326f99059ff775485246999027b3197955"
                      decimals: 18
                    amount:
                      base_atomic: "25000000000000000000"
                      payable_atomic: "25000137000000000000"
                      display_decimals: 18
                    payment:
                      address: "0x1111111111111111111111111111111111111111"
                      url: /pay/pub_9b1f4c7e2a8d4f6b0c3e5a7d9f1b2c4e
                    success_url: https://store.example/orders/1042/thanks
                    cancel_url: https://store.example/cart
                    customer:
                      email: sara@example.com
                      name: Sara Ali
                    expires_at: "2026-10-26T10:30:00Z"
                    created_at: "2026-10-26T10:00:00Z"
        "400":
          $ref: "#/components/responses/Problem"
        "401":
          $ref: "#/components/responses/Problem"
        "403":
          $ref: "#/components/responses/Problem"
        "409":
          $ref: "#/components/responses/Problem"
        "413":
          $ref: "#/components/responses/Problem"
        "422":
          $ref: "#/components/responses/Problem"
        "429":
          $ref: "#/components/responses/RateLimited"
        "503":
          $ref: "#/components/responses/Problem"
  /v1/invoices/{invoice_id}:
    parameters:
      - $ref: "#/components/parameters/InvoiceId"
    get:
      operationId: getInvoice
      tags: [Invoices]
      summary: Read one project invoice
      responses:
        "200":
          description: Invoice state.
          headers:
            X-RateLimit-Limit:
              $ref: "#/components/headers/RateLimitLimit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/RateLimitRemaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/RateLimitReset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Invoice"
        "401":
          $ref: "#/components/responses/Problem"
        "403":
          $ref: "#/components/responses/Problem"
        "404":
          $ref: "#/components/responses/Problem"
        "429":
          $ref: "#/components/responses/RateLimited"
        "503":
          $ref: "#/components/responses/Problem"
  /v1/invoices/{invoice_id}/cancel:
    parameters:
      - $ref: "#/components/parameters/InvoiceId"
    post:
      operationId: cancelInvoice
      tags: [Invoices]
      summary: Cancel a pending invoice using an expected revision
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [expected_revision]
              properties:
                expected_revision:
                  type: integer
                  minimum: 1
      responses:
        "200":
          description: Cancelled invoice state.
          headers:
            X-RateLimit-Limit:
              $ref: "#/components/headers/RateLimitLimit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/RateLimitRemaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/RateLimitReset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InvoiceMutation"
        "400":
          $ref: "#/components/responses/Problem"
        "401":
          $ref: "#/components/responses/Problem"
        "403":
          $ref: "#/components/responses/Problem"
        "409":
          $ref: "#/components/responses/Problem"
        "422":
          $ref: "#/components/responses/Problem"
        "429":
          $ref: "#/components/responses/RateLimited"
        "503":
          $ref: "#/components/responses/Problem"
  /v1/invoices/{invoice_id}/claim-transaction:
    parameters:
      - $ref: "#/components/parameters/InvoiceId"
    post:
      operationId: claimTransaction
      tags: [Invoices]
      summary: Submit a transaction for review without changing invoice payment state
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [tx_id]
              properties:
                tx_id:
                  type: string
                  minLength: 32
                  maxLength: 128
      responses:
        "202":
          description: Claim accepted for review.
          headers:
            X-RateLimit-Limit:
              $ref: "#/components/headers/RateLimitLimit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/RateLimitRemaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/RateLimitReset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TransactionClaim"
        "400":
          $ref: "#/components/responses/Problem"
        "401":
          $ref: "#/components/responses/Problem"
        "403":
          $ref: "#/components/responses/Problem"
        "409":
          $ref: "#/components/responses/Problem"
        "422":
          $ref: "#/components/responses/Problem"
        "429":
          $ref: "#/components/responses/RateLimited"
        "503":
          $ref: "#/components/responses/Problem"
  /v1/test/invoices/{invoice_id}/simulate:
    parameters:
      - $ref: "#/components/parameters/InvoiceId"
    post:
      operationId: simulateTestInvoice
      tags: [Sandbox]
      summary: Apply a fake-money scenario to a sandbox invoice
      description: |
        Requires a nbta_test_ API key. This endpoint never calls a blockchain,
        never uses a real receiving address, and never changes a live invoice.
        Read the result with `GET /v1/invoices/{invoice_id}` using the same
        test key; a sandbox invoice has no public checkout page.
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [scenario]
              properties:
                scenario:
                  type: string
                  enum:
                    - paid_immediately
                    - confirmation_delayed
                    - wrong_amount
                    - wrong_network
                    - expired_unpaid
                    - late_payment
                    - webhook_retry
      responses:
        "200":
          description: The isolated sandbox event produced by the scenario.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxEvent"
        "400":
          $ref: "#/components/responses/Problem"
        "401":
          $ref: "#/components/responses/Problem"
        "403":
          $ref: "#/components/responses/Problem"
        "404":
          $ref: "#/components/responses/Problem"
        "409":
          $ref: "#/components/responses/Problem"
        "422":
          $ref: "#/components/responses/Problem"
        "429":
          $ref: "#/components/responses/RateLimited"
        "503":
          $ref: "#/components/responses/Problem"
  /public/invoices/{public_id}:
    parameters:
      - name: public_id
        in: path
        required: true
        schema:
          type: string
          pattern: ^pub_[a-f0-9]{32}$
    get:
      operationId: getPublicInvoice
      tags: [Public checkout]
      security: []
      summary: Read the minimal public checkout projection
      description: |
        The payload includes `server_time`, the gateway clock for this
        response; judge `expires_at` against it, not the device clock. The
        endpoint answers `429` with `Retry-After` when the client address or
        the invoice exceeds its per-minute limit.
      responses:
        "200":
          description: Public invoice projection.
          headers:
            X-RateLimit-Limit:
              $ref: "#/components/headers/RateLimitLimit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/RateLimitRemaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/RateLimitReset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicInvoice"
        "404":
          $ref: "#/components/responses/Problem"
        "429":
          $ref: "#/components/responses/RateLimited"
        "503":
          $ref: "#/components/responses/Problem"
  /public/invoices/{public_id}/cancel:
    parameters:
      - name: public_id
        in: path
        required: true
        schema:
          type: string
          pattern: ^pub_[a-f0-9]{32}$
    post:
      operationId: cancelPublicInvoice
      tags: [Public checkout]
      security: []
      summary: The payer leaves an unpaid checkout
      description: |
        Called by the hosted checkout when the payer chooses Cancel and return.
        It cancels a still pending invoice that has a `cancel_url`, so the
        project receives the signed `invoice.cancelled` webhook at once instead
        of waiting for expiry. Repeating it is a no-op and sends no second
        event. A transfer that still arrives is reconciled as for any cancelled
        invoice. An invoice that is paid, expired, observed or has no
        `cancel_url` answers `409 invoice_not_cancellable`. Limited to 10
        requests a minute per client address and invoice.
      responses:
        "200":
          description: The invoice is cancelled.
          content:
            application/json:
              schema:
                type: object
                required: [status]
                properties:
                  status:
                    type: string
                    enum: [cancelled]
        "404":
          $ref: "#/components/responses/Problem"
        "409":
          $ref: "#/components/responses/Problem"
        "429":
          $ref: "#/components/responses/RateLimited"
        "503":
          $ref: "#/components/responses/Problem"
  /v1/account:
    get:
      operationId: getAccount
      tags: [Account]
      security:
        - AccountAgentKey: []
      summary: Read the owner, this key, available networks and wallets
      description: |
        Needs no scope. `wallets` is null unless the key holds `wallets:read`.
        `networks[].available` is false while payment monitoring on that
        network cannot accept new liability; such networks cannot be attached.
        `usdt_tron` (USDT on TRON) is paused and currently unavailable: it is
        not listed and cannot be attached or invoiced.
      responses:
        "200":
          description: Account overview.
          headers:
            X-RateLimit-Limit:
              $ref: "#/components/headers/RateLimitLimit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/RateLimitRemaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/RateLimitReset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AccountOverview"
              examples:
                overview:
                  value:
                    owner_id: 0b7e3c1a-2f4d-4a6b-8c9e-1d2f3a4b5c6d
                    key:
                      id: 5a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d
                      label: Fanio agent
                      prefix: nbta_acct_live_ab12cd34
                      scopes:
                        [
                          invoices:read,
                          invoices:write,
                          keys:write,
                          projects:read,
                          projects:write,
                          wallets:read,
                          webhooks:write,
                        ]
                      project_ids: null
                      expires_at: null
                      created_by: 0b7e3c1a-2f4d-4a6b-8c9e-1d2f3a4b5c6d
                      created_at: "2026-10-26T09:00:00Z"
                      last_used_at: "2026-10-26T10:00:00Z"
                      revoked_at: null
                      status: active
                    networks:
                      - network_asset_id: bsc_usd_bep20
                        asset_name: Binance-Peg BSC-USD
                        symbol: USDT
                        network: bsc_mainnet
                        network_standard: BEP-20
                        default_wallet_label: BSC USDT
                        available: true
                        status: available
                    wallets:
                      - id: 8d4c2b1a-6e5f-4a3b-9c8d-7e6f5a4b3c21
                        network_asset_id: bsc_usd_bep20
                        asset_name: Binance-Peg BSC-USD
                        symbol: USDT
                        network: bsc_mainnet
                        network_standard: BEP-20
                        address: "0x1111111111111111111111111111111111111111"
                        label: BSC USDT
                        created_at: "2026-10-20T08:00:00Z"
                        updated_at: "2026-10-20T08:00:00Z"
                        archived_at: null
                    project_count: 2
                    api_base_url: https://nbta.sbarah.com/api
                    checkout_base_url: https://nbta.sbarah.com/pay/
        "401":
          $ref: "#/components/responses/Problem"
        "429":
          $ref: "#/components/responses/RateLimited"
        "503":
          $ref: "#/components/responses/Problem"
  /v1/account/setup:
    post:
      operationId: setupAccountProject
      tags: [Account]
      security:
        - AccountAgentKey: [projects:write, keys:write]
      summary: Set up a project for an integration in one call
      description: |
        Scopes: `projects:write` and `keys:write`, plus `webhooks:write` when
        `webhook_url` is sent or `rotate_webhook` is true, and `invoices:read`
        or `invoices:write` (the project key receives the invoice scopes this
        key holds).

        Idempotent by slug: an existing project with the slug is reused, its
        current wallet per network kept. `slug` defaults to one derived from
        the `site_url` host, else the name.

        The project key is shown only once, on the call that creates it.
        Store `env` in the integrating project's `.env` on the first setup.
        A key is minted only when the project has no active live key or
        `rotate_key` is true (`key_created: true`, `api_key.api_key` holds the
        raw key). Otherwise `key_created` is false and `api_key` describes the
        newest active live key without its secret. The webhook endpoint is
        created when missing and updated when `webhook_url` differs;
        `webhook.changed` tells whether this call did either, and
        `webhook.signing_secret` is present only then. The same URL changes
        nothing. Pass `rotate_key: true` only when the stored key is lost,
        and `rotate_webhook: true` only to replace a leaked signing secret.

        `wallets[].receiving_address` is present only when the key holds
        `wallets:read`.

        When a requested network has no active wallet or more than one, the
        call changes nothing and answers 409 `wallet_selection_required`
        with `selections`. Repeat it with `wallet_ids` holding one choice per
        listed network, or ask the owner to add a wallet in the dashboard.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AccountSetupRequest"
            examples:
              store:
                summary: Store accepting USDT on BNB Smart Chain
                value:
                  name: Fanio
                  site_url: https://fanio.net
                  webhook_url: https://fanio.net/api/nbta/webhook
                  networks: [bsc_usd_bep20]
      responses:
        "200":
          description: |
            Existing project set up again. Without `rotate_key` no key is
            minted and no secret is returned.
          headers:
            X-RateLimit-Limit:
              $ref: "#/components/headers/RateLimitLimit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/RateLimitRemaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/RateLimitReset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AccountSetupResult"
              examples:
                repeated:
                  value:
                    status: ready
                    key_created: false
                    project:
                      id: 3f2a9c1e-7b4d-4e8a-9c2f-1d3e5a7b9c01
                      name: Fanio
                      slug: fanio-net
                      status: active
                      created: false
                    wallets:
                      - network_asset_id: bsc_usd_bep20
                        wallet_id: 8d4c2b1a-6e5f-4a3b-9c8d-7e6f5a4b3c21
                        receiving_address: "0x1111111111111111111111111111111111111111"
                        route_id: 6f1c2a4e-8b3d-4c5e-9a7f-0d2e4b6c8a10
                        changed: false
                    api_key:
                      id: 2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e
                      project_id: 3f2a9c1e-7b4d-4e8a-9c2f-1d3e5a7b9c01
                      prefix: nbta_live_1a2b3c4d5e6f7a8b
                      label: Agent setup
                      environment: live
                      scopes: [invoices:read, invoices:write]
                      created_at: "2026-10-26T10:00:00Z"
                    webhook:
                      id: 4d5e6f7a-8b9c-4d0e-8f1a-2b3c4d5e6f7a
                      project_id: 3f2a9c1e-7b4d-4e8a-9c2f-1d3e5a7b9c01
                      url: https://fanio.net/api/nbta/webhook
                      status: active
                      updated_at: "2026-10-26T10:00:00Z"
                      changed: false
                    site_url: https://fanio.net
                    api_base_url: https://nbta.sbarah.com/api
                    checkout_base_url: https://nbta.sbarah.com/pay/
                    env: |
                      # Nbta. Server-side only; never commit or expose these values.
                      NBTA_API_URL=https://nbta.sbarah.com/api
        "201":
          description: Project created and set up.
          headers:
            X-RateLimit-Limit:
              $ref: "#/components/headers/RateLimitLimit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/RateLimitRemaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/RateLimitReset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AccountSetupResult"
              examples:
                ready:
                  value:
                    status: ready
                    key_created: true
                    project:
                      id: 3f2a9c1e-7b4d-4e8a-9c2f-1d3e5a7b9c01
                      name: Fanio
                      slug: fanio-net
                      status: active
                      created: true
                    wallets:
                      - network_asset_id: bsc_usd_bep20
                        wallet_id: 8d4c2b1a-6e5f-4a3b-9c8d-7e6f5a4b3c21
                        receiving_address: "0x1111111111111111111111111111111111111111"
                        route_id: 6f1c2a4e-8b3d-4c5e-9a7f-0d2e4b6c8a10
                        changed: true
                    api_key:
                      id: 2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e
                      project_id: 3f2a9c1e-7b4d-4e8a-9c2f-1d3e5a7b9c01
                      prefix: nbta_live_1a2b3c4d5e6f7a8b
                      label: Agent setup
                      environment: live
                      scopes: [invoices:read, invoices:write]
                      api_key: nbta_live_1a2b3c4d5e6f7a8b_EXAMPLEONLYexampleONLYexampleONLY0123
                      created_at: "2026-10-26T10:00:00Z"
                    webhook:
                      id: 4d5e6f7a-8b9c-4d0e-8f1a-2b3c4d5e6f7a
                      project_id: 3f2a9c1e-7b4d-4e8a-9c2f-1d3e5a7b9c01
                      url: https://fanio.net/api/nbta/webhook
                      status: active
                      signing_secret: whsec_EXAMPLEONLYexampleONLYexampleONLYexample=
                      updated_at: "2026-10-26T10:00:00Z"
                      changed: true
                    site_url: https://fanio.net
                    api_base_url: https://nbta.sbarah.com/api
                    checkout_base_url: https://nbta.sbarah.com/pay/
                    env: |
                      # Nbta. Server-side only; never commit or expose these values.
                      NBTA_API_URL=https://nbta.sbarah.com/api
                      NBTA_API_KEY=nbta_live_1a2b3c4d5e6f7a8b_EXAMPLEONLYexampleONLYexampleONLY0123
                      NBTA_WEBHOOK_SECRET=whsec_EXAMPLEONLYexampleONLYexampleONLYexample=
        "400":
          $ref: "#/components/responses/Problem"
        "401":
          $ref: "#/components/responses/Problem"
        "403":
          $ref: "#/components/responses/Problem"
        "404":
          $ref: "#/components/responses/Problem"
        "409":
          description: |
            `wallet_selection_required` (with `selections`),
            `network_unavailable` or `project_slug_conflict`.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
              examples:
                walletSelectionRequired:
                  value:
                    type: https://nbta.sbarah.com/docs/errors/wallet_selection_required
                    title: Wallet Selection Required
                    status: 409
                    code: wallet_selection_required
                    detail: Choose one wallet per listed network and repeat the call with wallet_ids, or add a wallet in the dashboard. Nothing was changed.
                    request_id: 9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d
                    selections:
                      - network_asset_id: bsc_usd_bep20
                        reason: multiple_wallets
                        choices:
                          - id: 8d4c2b1a-6e5f-4a3b-9c8d-7e6f5a4b3c21
                            label: BSC USDT
                            address: "0x1111111111111111111111111111111111111111"
                          - id: 1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f
                            label: Cold wallet
                            address: "0x2222222222222222222222222222222222222222"
        "413":
          $ref: "#/components/responses/Problem"
        "429":
          $ref: "#/components/responses/RateLimited"
        "503":
          $ref: "#/components/responses/Problem"
  /v1/account/projects:
    get:
      operationId: listAccountProjects
      tags: [Account]
      security:
        - AccountAgentKey: [projects:read]
      summary: List the projects this key can reach
      responses:
        "200":
          description: Projects with their attached wallets and webhook.
          headers:
            X-RateLimit-Limit:
              $ref: "#/components/headers/RateLimitLimit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/RateLimitRemaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/RateLimitReset"
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/AccountProject"
              examples:
                projects:
                  value:
                    data:
                      - id: 3f2a9c1e-7b4d-4e8a-9c2f-1d3e5a7b9c01
                        name: Fanio
                        slug: fanio-net
                        status: active
                        created_at: "2026-10-26T10:00:00Z"
                        payer_receipts_enabled: false
                        wallets:
                          - network_asset_id: bsc_usd_bep20
                            wallet_id: 8d4c2b1a-6e5f-4a3b-9c8d-7e6f5a4b3c21
                            receiving_address: "0x1111111111111111111111111111111111111111"
                            route_id: 6f1c2a4e-8b3d-4c5e-9a7f-0d2e4b6c8a10
                            is_default: true
                        webhook:
                          id: 4d5e6f7a-8b9c-4d0e-8f1a-2b3c4d5e6f7a
                          url: https://fanio.net/api/nbta/webhook
                          status: active
                        active_api_keys: 1
        "401":
          $ref: "#/components/responses/Problem"
        "403":
          $ref: "#/components/responses/Problem"
        "429":
          $ref: "#/components/responses/RateLimited"
        "503":
          $ref: "#/components/responses/Problem"
    post:
      operationId: createAccountProject
      tags: [Account]
      security:
        - AccountAgentKey: [projects:write]
      summary: Create a project
      description: Refused with `project_not_allowed` for keys restricted to selected projects.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [name]
              properties:
                name:
                  type: string
                  minLength: 2
                  maxLength: 80
                slug:
                  $ref: "#/components/schemas/ProjectSlug"
            examples:
              project:
                value:
                  name: Fanio
                  slug: fanio
      responses:
        "201":
          description: Project created.
          headers:
            X-RateLimit-Limit:
              $ref: "#/components/headers/RateLimitLimit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/RateLimitRemaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/RateLimitReset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AccountCreatedProject"
              examples:
                created:
                  value:
                    id: 3f2a9c1e-7b4d-4e8a-9c2f-1d3e5a7b9c01
                    name: Fanio
                    slug: fanio
                    status: active
                    created_at: "2026-10-26T10:00:00Z"
        "400":
          $ref: "#/components/responses/Problem"
        "401":
          $ref: "#/components/responses/Problem"
        "403":
          $ref: "#/components/responses/Problem"
        "409":
          $ref: "#/components/responses/Problem"
        "413":
          $ref: "#/components/responses/Problem"
        "429":
          $ref: "#/components/responses/RateLimited"
        "503":
          $ref: "#/components/responses/Problem"
  /v1/account/projects/{project_id}:
    parameters:
      - $ref: "#/components/parameters/ProjectId"
    patch:
      operationId: updateAccountProject
      tags: [Account]
      security:
        - AccountAgentKey: [projects:write]
      summary: Rename, disable or re-enable a project, or set payer receipts
      description: |
        Partial update: send any of `name`, `status` and
        `payer_receipts_enabled`; a field that is not sent keeps its current
        value. Needs `projects:write` only. `payer_receipts_enabled: true`
        emails each payer whose invoice carries `customer.email` a receipt once
        it is paid, so turn it on only after the owner agreed. Every change is
        audited.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              minProperties: 1
              properties:
                name:
                  type: string
                  minLength: 2
                  maxLength: 80
                status:
                  type: string
                  enum: [active, disabled]
                payer_receipts_enabled:
                  type: boolean
                  description: Email the payer a receipt once an invoice that carries customer.email is paid or late_paid.
            examples:
              rename:
                value:
                  name: Fanio Store
              receipts:
                value:
                  payer_receipts_enabled: true
      responses:
        "200":
          description: Project after the update.
          headers:
            X-RateLimit-Limit:
              $ref: "#/components/headers/RateLimitLimit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/RateLimitRemaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/RateLimitReset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AccountCreatedProject"
        "400":
          $ref: "#/components/responses/Problem"
        "401":
          $ref: "#/components/responses/Problem"
        "403":
          $ref: "#/components/responses/Problem"
        "404":
          $ref: "#/components/responses/Problem"
        "413":
          $ref: "#/components/responses/Problem"
        "429":
          $ref: "#/components/responses/RateLimited"
        "503":
          $ref: "#/components/responses/Problem"
  /v1/account/projects/{project_id}/wallets:
    parameters:
      - $ref: "#/components/parameters/ProjectId"
    put:
      operationId: setAccountProjectWallets
      tags: [Account]
      security:
        - AccountAgentKey: [projects:write]
      summary: Attach existing account wallets to a project, one per network
      description: |
        Atomic: every entry is applied in one database transaction, so either
        all entries take effect or none does (a failed request changes
        nothing and is safe to repeat). Each network may appear once.
        `wallet_id: null` detaches the network and needs `wallets:write`;
        every network that gets a new wallet must be available
        (`networks[].available`) or the whole request answers 409
        `network_unavailable`. Only wallets already on the account can be
        attached; adding a receiving address needs `wallets:write`
        (`POST /v1/account/wallets`). `route.receiving_address` is present
        only when the key holds `wallets:read`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [wallets]
              properties:
                wallets:
                  type: array
                  minItems: 1
                  maxItems: 10
                  items:
                    type: object
                    additionalProperties: false
                    required: [network_asset_id, wallet_id]
                    properties:
                      network_asset_id:
                        $ref: "#/components/schemas/NetworkAssetId"
                      wallet_id:
                        type: [string, "null"]
                        format: uuid
            examples:
              attach:
                value:
                  wallets:
                    - network_asset_id: bsc_usd_bep20
                      wallet_id: 8d4c2b1a-6e5f-4a3b-9c8d-7e6f5a4b3c21
      responses:
        "200":
          description: All entries applied, one result per entry, ordered by network_asset_id.
          headers:
            X-RateLimit-Limit:
              $ref: "#/components/headers/RateLimitLimit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/RateLimitRemaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/RateLimitReset"
          content:
            application/json:
              schema:
                type: object
                required: [project_id, data]
                properties:
                  project_id:
                    type: string
                    format: uuid
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/ProjectWalletAssignment"
              examples:
                attached:
                  value:
                    project_id: 3f2a9c1e-7b4d-4e8a-9c2f-1d3e5a7b9c01
                    data:
                      - changed: true
                        network_asset_id: bsc_usd_bep20
                        wallet_id: 8d4c2b1a-6e5f-4a3b-9c8d-7e6f5a4b3c21
                        route:
                          id: 6f1c2a4e-8b3d-4c5e-9a7f-0d2e4b6c8a10
                          project_id: 3f2a9c1e-7b4d-4e8a-9c2f-1d3e5a7b9c01
                          network_asset_id: bsc_usd_bep20
                          receiving_address: "0x1111111111111111111111111111111111111111"
                          owner_wallet_id: 8d4c2b1a-6e5f-4a3b-9c8d-7e6f5a4b3c21
                          status: active
                          is_default: true
        "400":
          $ref: "#/components/responses/Problem"
        "401":
          $ref: "#/components/responses/Problem"
        "403":
          $ref: "#/components/responses/Problem"
        "404":
          $ref: "#/components/responses/Problem"
        "409":
          $ref: "#/components/responses/Problem"
        "413":
          $ref: "#/components/responses/Problem"
        "429":
          $ref: "#/components/responses/RateLimited"
        "503":
          $ref: "#/components/responses/Problem"
  /v1/account/projects/{project_id}/keys:
    parameters:
      - $ref: "#/components/parameters/ProjectId"
    post:
      operationId: createAccountProjectKey
      tags: [Account]
      security:
        - AccountAgentKey: [keys:write]
      summary: Issue a project API key
      description: |
        The key's scopes must be a subset of the agent key's scopes. The raw
        `api_key` is returned once; write it to the project's `.env` as
        `NBTA_API_KEY`. The key records the member who created the agent key
        and is revoked if that member is removed or demoted.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                label:
                  type: string
                  minLength: 2
                  maxLength: 80
                  default: Agent key
                scopes:
                  type: array
                  minItems: 1
                  items:
                    type: string
                    enum: [invoices:read, invoices:write]
                  default: [invoices:read, invoices:write]
                environment:
                  type: string
                  enum: [live, test]
                  default: live
            examples:
              live:
                value:
                  label: Fanio production
      responses:
        "201":
          description: Key created. `api_key` is shown only here.
          headers:
            X-RateLimit-Limit:
              $ref: "#/components/headers/RateLimitLimit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/RateLimitRemaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/RateLimitReset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreatedProjectKey"
        "400":
          $ref: "#/components/responses/Problem"
        "401":
          $ref: "#/components/responses/Problem"
        "403":
          $ref: "#/components/responses/Problem"
        "404":
          $ref: "#/components/responses/Problem"
        "413":
          $ref: "#/components/responses/Problem"
        "429":
          $ref: "#/components/responses/RateLimited"
        "503":
          $ref: "#/components/responses/Problem"
  /v1/account/projects/{project_id}/webhooks:
    parameters:
      - $ref: "#/components/parameters/ProjectId"
    post:
      operationId: createAccountProjectWebhook
      tags: [Account]
      security:
        - AccountAgentKey: [webhooks:write]
      summary: Set the project's webhook endpoint and rotate its signing secret
      description: |
        A project has one endpoint. Calling this again changes the URL and
        rotates the secret; the previous secret stays valid for one hour.
        Write `signing_secret` to the project's `.env` as `NBTA_WEBHOOK_SECRET`.
        Saving an endpoint also releases events held for up to 7 days after a
        previous endpoint answered `410`; they are sent again in their
        original order.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [url]
              properties:
                url:
                  type: string
                  format: uri
                  maxLength: 2048
                  pattern: ^https://
            examples:
              endpoint:
                value:
                  url: https://fanio.net/api/nbta/webhook
      responses:
        "201":
          description: Endpoint set. `signing_secret` is shown only here.
          headers:
            X-RateLimit-Limit:
              $ref: "#/components/headers/RateLimitLimit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/RateLimitRemaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/RateLimitReset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreatedWebhookEndpoint"
        "400":
          $ref: "#/components/responses/Problem"
        "401":
          $ref: "#/components/responses/Problem"
        "403":
          $ref: "#/components/responses/Problem"
        "404":
          $ref: "#/components/responses/Problem"
        "413":
          $ref: "#/components/responses/Problem"
        "429":
          $ref: "#/components/responses/RateLimited"
        "503":
          $ref: "#/components/responses/Problem"
  /v1/account/projects/{project_id}/webhook:
    parameters:
      - $ref: "#/components/parameters/ProjectId"
    get:
      operationId: getAccountProjectWebhookStatus
      tags: [Account]
      security:
        - AccountAgentKey: [projects:read]
      summary: Read the project's webhook health
      description: |
        Read only. Reports whether the project has an endpoint, its status,
        how many events wait in each state and the latest delivery attempt.
        An endpoint that answered `410` is `disabled`; the project's other
        pending events are then `held` for up to 7 days and `earliest_held_until`
        shows the soonest hold end. Saving a new endpoint
        (`POST /v1/account/projects/{project_id}/webhooks`) sends held events
        again in their original order; held events that pass their hold become
        `expired` and are never deleted. The response never contains a signing
        secret, a signature or an event payload.
      responses:
        "200":
          description: Webhook health of the project.
          headers:
            X-RateLimit-Limit:
              $ref: "#/components/headers/RateLimitLimit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/RateLimitRemaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/RateLimitReset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookStatus"
        "401":
          $ref: "#/components/responses/Problem"
        "403":
          $ref: "#/components/responses/Problem"
        "404":
          $ref: "#/components/responses/Problem"
        "429":
          $ref: "#/components/responses/RateLimited"
        "503":
          $ref: "#/components/responses/Problem"
  /v1/account/wallets:
    get:
      operationId: listAccountWallets
      tags: [Account]
      security:
        - AccountAgentKey: [wallets:read]
      summary: List the account's receiving wallets
      description: |
        Active wallets by default; `include_archived=true` adds archived ones.
        `projects` lists the projects each wallet receives for, limited to the
        projects this key can reach.
      parameters:
        - name: include_archived
          in: query
          required: false
          schema:
            type: boolean
            default: false
      responses:
        "200":
          description: Receiving wallets with the projects they are attached to.
          headers:
            X-RateLimit-Limit:
              $ref: "#/components/headers/RateLimitLimit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/RateLimitRemaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/RateLimitReset"
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/AccountWallet"
        "401":
          $ref: "#/components/responses/Problem"
        "403":
          $ref: "#/components/responses/Problem"
        "429":
          $ref: "#/components/responses/RateLimited"
        "503":
          $ref: "#/components/responses/Problem"
    post:
      operationId: createAccountWallet
      tags: [Account]
      security:
        - AccountAgentKey: [wallets:write]
      summary: Add a receiving wallet to the account
      description: |
        Needs `wallets:write`, which is off by default because a receiving
        address decides where money goes. Prefer asking the owner to add
        wallets in the dashboard. Refused with 409 `network_unavailable` while
        monitoring on the network cannot accept new liability.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [network_asset_id, address]
              properties:
                network_asset_id:
                  $ref: "#/components/schemas/NetworkAssetId"
                address:
                  type: string
                  minLength: 20
                  maxLength: 128
                label:
                  type: string
                  minLength: 1
                  maxLength: 80
            examples:
              bsc:
                value:
                  network_asset_id: bsc_usd_bep20
                  address: "0x1111111111111111111111111111111111111111"
                  label: BSC USDT
      responses:
        "201":
          description: Wallet created.
          headers:
            X-RateLimit-Limit:
              $ref: "#/components/headers/RateLimitLimit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/RateLimitRemaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/RateLimitReset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AccountWallet"
        "400":
          $ref: "#/components/responses/Problem"
        "401":
          $ref: "#/components/responses/Problem"
        "403":
          $ref: "#/components/responses/Problem"
        "409":
          $ref: "#/components/responses/Problem"
        "413":
          $ref: "#/components/responses/Problem"
        "429":
          $ref: "#/components/responses/RateLimited"
        "503":
          $ref: "#/components/responses/Problem"
webhooks:
  invoice.paid:
    post:
      operationId: invoicePaidWebhook
      tags: [Webhooks]
      security: []
      summary: An invoice settled with a transfer inside its payment window
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/InvoiceSettledEvent"
            examples:
              overpaid:
                summary: Paid with a small overpayment, with customer
                value:
                  id: evt_5c2e9a1f7b3d4e8a6f0b1c2d3e4f5a6b
                  type: invoice.paid
                  created_at: "2026-10-26T10:07:12Z"
                  data:
                    invoice:
                      id: 3f8e2b1c-5d7a-4e9b-8c6d-1a2b3c4d5e6f
                      public_id: pub_9b1f4c7e2a8d4f6b0c3e5a7d9f1b2c4e
                      external_id: order-1042
                      status: paid
                      payable_amount_atomic: "25000137000000000000"
                      received_amount_atomic: "25500137000000000000"
                      overpaid_amount_atomic: "500000000000000000"
                      payment_route: bsc_usd_bep20
                      customer:
                        email: sara@example.com
                        name: Sara Ali
                      transaction:
                        tx_id: "0x9f2b6d0c4a8e1f3b5d7c9e0a2b4c6d8e0f1a3b5c7d9e1f2a4b6c8d0e2f4a6b8c"
                        log_index: 0
                        block_number: "66120344"
      responses:
        "200":
          description: Any 2xx response acknowledges the event.
  invoice.late_paid:
    post:
      operationId: invoiceLatePaidWebhook
      tags: [Webhooks]
      security: []
      summary: An invoice settled with a transfer after its expiry but inside monitoring
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/InvoiceSettledEvent"
      responses:
        "200":
          description: Any 2xx response acknowledges the event.
components:
  securitySchemes:
    ProjectKey:
      type: http
      scheme: bearer
      bearerFormat: nbta_test_<prefix>_<secret>
      description: Project-scoped key. It is shown once and must remain server-side.
    AccountAgentKey:
      type: http
      scheme: bearer
      bearerFormat: nbta_acct_live_<64 hex>
      description: |
        Account agent key created by the owner in the dashboard. Only valid on
        `/v1/account/*`. Scopes: projects:read, projects:write, keys:write,
        webhooks:write, invoices:read, invoices:write, wallets:read,
        wallets:write (off by default). It may be restricted to selected
        projects. Keep it in the agent's environment, never in a repository.
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      schema:
        type: string
        minLength: 16
        maxLength: 128
    ProjectId:
      name: project_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    InvoiceId:
      name: invoice_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
  headers:
    RateLimitLimit:
      description: Maximum requests allowed in the current fixed window.
      schema:
        type: integer
        minimum: 1
    RateLimitRemaining:
      description: Requests remaining in the current fixed window.
      schema:
        type: integer
        minimum: 0
    RateLimitReset:
      description: UTC timestamp when the current fixed window resets.
      schema:
        type: string
        format: date-time
    RetryAfter:
      description: Seconds until a rate-limited request may be retried.
      schema:
        type: integer
        minimum: 1
  responses:
    Problem:
      description: RFC 9457-style problem response.
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
    RateLimited:
      description: The caller exhausted the current fixed-window quota.
      headers:
        X-RateLimit-Limit:
          $ref: "#/components/headers/RateLimitLimit"
        X-RateLimit-Remaining:
          $ref: "#/components/headers/RateLimitRemaining"
        X-RateLimit-Reset:
          $ref: "#/components/headers/RateLimitReset"
        Retry-After:
          $ref: "#/components/headers/RetryAfter"
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
  schemas:
    InvoiceStatus:
      type: string
      enum:
        - pending
        - observed
        - paid
        - expired
        - late_paid
        - payment_exception
        - cancelled
    NetworkStandard:
      type: string
      description: TRC-20 belongs to `usdt_tron`, which is paused and currently unavailable.
      enum: [TRC-20, BEP-20, ERC-20]
    AtomicAmount:
      type: string
      pattern: ^[0-9]+$
      description: Integer atomic units serialized as a string.
    NullableAtomicAmount:
      type: [string, "null"]
      pattern: ^[0-9]+$
      description: Integer atomic units serialized as a string, or null.
    Health:
      type: object
      additionalProperties: false
      required: [status, service, environment]
      properties:
        status:
          const: ok
        service:
          const: nbta-gateway
        environment:
          type: string
    PaymentRoute:
      type: object
      additionalProperties: false
      required:
        - id
        - route
        - display_name
        - network
        - network_standard
        - contract
        - decimals
        - receiving_address
        - is_default
      properties:
        monitoring_available:
          type: boolean
          description: Whether payment monitoring is currently available.
        monitoring_status:
          type: string
          enum: [available, monitoring_unavailable]
        id:
          type: string
          format: uuid
        route:
          type: string
          description: "`usdt_tron` is paused and currently unavailable."
          enum:
            - usdt_tron
            - bsc_usd_bep20
            - usdc_bsc
            - polygon_usdc
            - polygon_usdt
            - base_usdc
            - base_usdt
            - arbitrum_usdc
            - arbitrum_usdt
            - nbta_sandbox_usdt
        display_name:
          type: string
        network:
          type: string
        network_standard:
          $ref: "#/components/schemas/NetworkStandard"
        chain_id:
          type: [string, "null"]
        contract:
          type: [string, "null"]
        decimals:
          type: integer
          minimum: 0
          maximum: 30
        receiving_address:
          type: [string, "null"]
        is_default:
          type: boolean
    CreateInvoiceRequest:
      type: object
      additionalProperties: false
      required: [external_id, amount, payment_route_id]
      properties:
        external_id:
          type: string
          minLength: 1
          maxLength: 128
        amount:
          type: string
          pattern: ^[0-9]{1,12}(?:\.[0-9]{1,6})?$
        payment_route_id:
          type: string
          format: uuid
        expires_in_seconds:
          type: integer
          minimum: 300
          maximum: 3600
        metadata:
          type: object
          additionalProperties: true
          maxProperties: 32
        success_url:
          $ref: "#/components/schemas/ReturnUrl"
          description: Where the hosted checkout sends the payer after a paid or late_paid invoice.
        cancel_url:
          $ref: "#/components/schemas/ReturnUrl"
          description: Where the hosted checkout sends the payer who goes back before paying.
        customer:
          $ref: "#/components/schemas/CustomerInput"
    ReturnUrl:
      type: string
      format: uri
      minLength: 9
      maxLength: 2048
      pattern: ^https?://
      description: |
        Absolute https URL without user info, whitespace, bidirectional
        overrides or zero width characters. Test API keys may also use http
        on localhost, 127.0.0.1 or [::1].
    CustomerInput:
      type: object
      additionalProperties: false
      minProperties: 1
      anyOf:
        - required: [email]
        - required: [name]
      description: |
        Optional customer details with email, name or both. Never shown on the
        public checkout. When the project turned on payer receipts, the email
        also receives one receipt once the invoice is paid or late_paid.
      properties:
        email:
          type: string
          format: email
          maxLength: 254
        name:
          type: string
          minLength: 1
          maxLength: 120
          description: |
            Trimmed before storage; 1 to 120 characters after trimming, without
            control characters, bidirectional overrides or zero width
            characters.
    Customer:
      type: [object, "null"]
      additionalProperties: false
      required: [email, name]
      description: Customer details sent at creation, or null when none were sent.
      properties:
        email:
          type: [string, "null"]
          format: email
        name:
          type: [string, "null"]
    NullableReturnUrl:
      type: [string, "null"]
      format: uri
      maxLength: 2048
    Asset:
      type: object
      additionalProperties: false
      required:
        - route
        - display_name
        - network
        - network_standard
        - contract
        - decimals
      properties:
        route:
          type: string
          description: "`usdt_tron` is paused and currently unavailable."
          enum:
            - usdt_tron
            - bsc_usd_bep20
            - usdc_bsc
            - polygon_usdc
            - polygon_usdt
            - base_usdc
            - base_usdt
            - arbitrum_usdc
            - arbitrum_usdt
            - nbta_sandbox_usdt
        display_name:
          type: string
        network:
          type: string
        network_standard:
          $ref: "#/components/schemas/NetworkStandard"
        chain_id:
          type: [string, "null"]
        contract:
          type: [string, "null"]
        decimals:
          type: integer
    CreatedInvoice:
      type: object
      additionalProperties: false
      required:
        - id
        - public_id
        - external_id
        - status
        - asset
        - amount
        - payment
        - expires_at
        - created_at
      properties:
        id:
          type: string
          format: uuid
        public_id:
          type: string
          description: |
            `pub_<32 hex>` for a live invoice. A sandbox invoice (test key) has
            `sandbox_<32 hex>`; it is not served by `/public/invoices`.
        external_id:
          type: string
        status:
          $ref: "#/components/schemas/InvoiceStatus"
        livemode:
          type: boolean
        environment:
          type: string
          enum: [test, live]
        asset:
          $ref: "#/components/schemas/Asset"
        amount:
          type: object
          additionalProperties: false
          required: [base_atomic, payable_atomic, display_decimals]
          properties:
            base_atomic:
              $ref: "#/components/schemas/AtomicAmount"
            payable_atomic:
              $ref: "#/components/schemas/AtomicAmount"
            display_decimals:
              type: integer
        payment:
          type: object
          additionalProperties: false
          required: [address, url]
          properties:
            address:
              type: string
            url:
              type: string
        success_url:
          $ref: "#/components/schemas/NullableReturnUrl"
        cancel_url:
          $ref: "#/components/schemas/NullableReturnUrl"
        customer:
          $ref: "#/components/schemas/Customer"
        expires_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
    Invoice:
      type: object
      additionalProperties: false
      required:
        - id
        - external_id
        - status
        - revision
        - base_amount_atomic
        - payable_amount_atomic
        - display_decimals
        - expires_at
        - created_at
        - updated_at
        - payment_route
      properties:
        id:
          type: string
          format: uuid
        external_id:
          type: string
        status:
          $ref: "#/components/schemas/InvoiceStatus"
        livemode:
          type: boolean
        environment:
          type: string
          enum: [test, live]
        revision:
          type: integer
          minimum: 1
        base_amount_atomic:
          $ref: "#/components/schemas/AtomicAmount"
        payable_amount_atomic:
          $ref: "#/components/schemas/AtomicAmount"
        received_amount_atomic:
          $ref: "#/components/schemas/NullableAtomicAmount"
          description: Finalized amount of the transfer that settled the invoice. Null until settled.
        overpaid_amount_atomic:
          $ref: "#/components/schemas/NullableAtomicAmount"
          description: Amount received above the payable amount. "0" for an exact payment, null until settled.
        display_decimals:
          type: integer
        expires_at:
          type: string
          format: date-time
        observed_at:
          type: [string, "null"]
          format: date-time
        paid_at:
          type: [string, "null"]
          format: date-time
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        payment_route:
          type: string
        success_url:
          $ref: "#/components/schemas/NullableReturnUrl"
        cancel_url:
          $ref: "#/components/schemas/NullableReturnUrl"
        customer:
          $ref: "#/components/schemas/Customer"
    InvoicePage:
      type: object
      additionalProperties: false
      required: [data, page]
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/Invoice"
        page:
          type: object
          additionalProperties: false
          required: [has_more, next_cursor]
          properties:
            has_more:
              type: boolean
            next_cursor:
              type: [string, "null"]
    InvoiceMutation:
      type: object
      additionalProperties: false
      required: [id, status, revision, updated_at]
      properties:
        id:
          type: string
          format: uuid
        status:
          $ref: "#/components/schemas/InvoiceStatus"
        revision:
          type: integer
        updated_at:
          type: string
          format: date-time
    TransactionClaim:
      type: object
      additionalProperties: false
      required:
        - id
        - invoice_id
        - tx_id
        - status
        - created_at
        - invoice_status_changed
      properties:
        id:
          type: string
          format: uuid
        invoice_id:
          type: string
          format: uuid
        tx_id:
          type: string
        status:
          type: string
          enum: [submitted, reviewing, accepted, rejected]
        created_at:
          type: string
          format: date-time
        invoice_status_changed:
          const: false
    SandboxEvent:
      type: object
      additionalProperties: false
      required: [id, type, livemode, environment, delivery_status, data]
      properties:
        id:
          type: string
          pattern: ^evt_test_
        type:
          type: string
          pattern: ^invoice\.
        livemode:
          const: false
        environment:
          const: test
        delivery_status:
          type: string
          enum: [delivered, retrying]
        data:
          type: object
          additionalProperties: false
          required: [invoice_id, status, transaction_id, scenario]
          properties:
            invoice_id:
              type: string
              format: uuid
            status:
              $ref: "#/components/schemas/InvoiceStatus"
            transaction_id:
              type: string
              pattern: ^sim_tx_
            scenario:
              type: string
            customer:
              $ref: "#/components/schemas/Customer"
    PublicInvoice:
      type: object
      additionalProperties: false
      required:
        - public_id
        - project_name
        - status
        - payable_amount_atomic
        - display_decimals
        - expires_at
        - receiving_address
        - payment_route
        - display_name
        - network
        - network_standard
        - contract_address
      properties:
        monitoring_available_until:
          type: [string, "null"]
          format: date-time
        monitoring_available:
          type: boolean
          description: Whether payment monitoring is currently available.
        monitoring_status:
          type: string
          enum: [available, monitoring_unavailable]
        server_time:
          type: string
          format: date-time
          description: |
            The gateway clock when this response was produced. Compare
            `expires_at` with this time, not with the device clock, so a device
            with a wrong clock does not show the invoice expired early or late.
        public_id:
          type: string
        project_name:
          type: string
        status:
          $ref: "#/components/schemas/InvoiceStatus"
        payable_amount_atomic:
          $ref: "#/components/schemas/AtomicAmount"
        accepted_max_amount_atomic:
          $ref: "#/components/schemas/AtomicAmount"
          description: |
            Highest transfer that still settles this invoice automatically:
            the payable amount plus the larger of one whole token and 5% of
            the payable amount, rounded down to a whole atomic unit.
        received_amount_atomic:
          $ref: "#/components/schemas/NullableAtomicAmount"
          description: Finalized amount of the transfer that settled the invoice. Null until settled.
        overpaid_amount_atomic:
          $ref: "#/components/schemas/NullableAtomicAmount"
          description: Amount received above the payable amount. "0" for an exact payment, null until settled.
        display_decimals:
          type: integer
        expires_at:
          type: string
          format: date-time
        observed_at:
          type: [string, "null"]
          format: date-time
        paid_at:
          type: [string, "null"]
          format: date-time
        receiving_address:
          type: [string, "null"]
        payment_route:
          type: string
        display_name:
          type: string
        network:
          type: string
        network_standard:
          $ref: "#/components/schemas/NetworkStandard"
        chain_id:
          type: [string, "null"]
        contract_address:
          type: string
        explorer_base_url:
          type: string
          format: uri
          description: Transaction URL prefix of the network's explorer. Append `transaction.tx_id` to link the settling transfer.
        finality_confirmations:
          type: integer
          minimum: 0
          description: |
            The network's finality depth. 0 or 1 means the gateway counts a
            transfer once its block is at or below the provider's finalized
            head; a depth N above 1 also holds back the newest N - 1
            finalized blocks. The gateway only settles finalized transfers,
            so a transfer appears here once and does not move back.
        transaction:
          oneOf:
            - $ref: "#/components/schemas/PublicSettlingTransaction"
            - type: "null"
          description: The finalized transfer that settled the invoice. Null until the invoice is matched.
        receipt_email:
          type: boolean
          description: |
            True when the payer will get a receipt email: for a paid or
            late_paid invoice, a receipt is queued, being sent or sent; for an
            open invoice, one will be queued when it is paid (the project
            opted in, the invoice carries a customer email and the mailer is
            configured). False for a receipt that failed or was cancelled.
            The address itself is never public.
        success_url:
          $ref: "#/components/schemas/NullableReturnUrl"
          description: The merchant's success_url, present only once the invoice is paid or late_paid.
        cancel_url:
          $ref: "#/components/schemas/NullableReturnUrl"
          description: The merchant's cancel_url, present only while the invoice is not paid.
    PublicSettlingTransaction:
      type: object
      additionalProperties: false
      required: [tx_id, block_timestamp, finalized_at]
      properties:
        tx_id:
          type: string
          minLength: 32
          maxLength: 128
          pattern: ^(?:0x)?[0-9a-fA-F]{30,128}$
          description: Hex hash, bare on TRON and 0x prefixed on EVM networks. Safe to append to `explorer_base_url`.
        block_timestamp:
          type: string
          format: date-time
        finalized_at:
          type: [string, "null"]
          format: date-time
    InvoiceSettledEvent:
      type: object
      required: [id, type, created_at, data]
      properties:
        id:
          type: string
          pattern: ^evt_
        type:
          type: string
          enum: [invoice.paid, invoice.late_paid]
        created_at:
          type: string
          format: date-time
        data:
          type: object
          required: [invoice]
          properties:
            invoice:
              type: object
              required:
                - id
                - public_id
                - external_id
                - status
                - payable_amount_atomic
                - received_amount_atomic
                - overpaid_amount_atomic
                - payment_route
                - transaction
              properties:
                id:
                  type: string
                  format: uuid
                public_id:
                  type: string
                external_id:
                  type: string
                status:
                  type: string
                  enum: [paid, late_paid]
                payable_amount_atomic:
                  $ref: "#/components/schemas/AtomicAmount"
                received_amount_atomic:
                  $ref: "#/components/schemas/AtomicAmount"
                overpaid_amount_atomic:
                  $ref: "#/components/schemas/AtomicAmount"
                payment_route:
                  type: string
                customer:
                  $ref: "#/components/schemas/Customer"
                transaction:
                  type: object
                  required: [tx_id, log_index, block_number]
                  properties:
                    tx_id:
                      type: string
                    log_index:
                      type: integer
                    block_number:
                      type: string
    AccountScope:
      type: string
      enum:
        - projects:read
        - projects:write
        - keys:write
        - webhooks:write
        - invoices:read
        - invoices:write
        - wallets:read
        - wallets:write
    NetworkAssetId:
      type: string
      pattern: ^[a-z0-9_]{2,40}$
      description: |
        Payment network and asset. `usdt_tron` (USDT on TRON) is paused and
        currently unavailable: routes on it are not listed, invoices on it
        fail with `payment_route_unavailable` and wallets cannot be attached
        to it.
      examples:
        - bsc_usd_bep20
        - usdc_bsc
        - polygon_usdc
        - polygon_usdt
        - base_usdc
        - base_usdt
        - arbitrum_usdc
        - arbitrum_usdt
    ProjectSlug:
      type: string
      minLength: 2
      maxLength: 48
      pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
    AccountAgentKeyInfo:
      type: object
      required:
        [
          id,
          label,
          prefix,
          scopes,
          project_ids,
          expires_at,
          created_at,
          last_used_at,
          revoked_at,
          status,
        ]
      properties:
        id:
          type: string
          format: uuid
        label:
          type: string
        prefix:
          type: string
        scopes:
          type: array
          items:
            $ref: "#/components/schemas/AccountScope"
        project_ids:
          type: [array, "null"]
          items:
            type: string
            format: uuid
        expires_at:
          type: [string, "null"]
          format: date-time
        created_by:
          type: [string, "null"]
          format: uuid
        created_at:
          type: string
          format: date-time
        last_used_at:
          type: [string, "null"]
          format: date-time
        revoked_at:
          type: [string, "null"]
          format: date-time
        status:
          type: string
          enum: [active, expired, revoked]
    AccountNetwork:
      type: object
      required:
        [
          network_asset_id,
          asset_name,
          symbol,
          network,
          network_standard,
          available,
          status,
        ]
      properties:
        network_asset_id:
          $ref: "#/components/schemas/NetworkAssetId"
        asset_name:
          type: string
        symbol:
          type: string
        network:
          type: string
        network_standard:
          type: string
        default_wallet_label:
          type: string
        available:
          type: boolean
        status:
          type: string
          enum: [available, monitoring_unavailable]
    AccountWallet:
      type: object
      required: [id, network_asset_id, address, label]
      properties:
        id:
          type: string
          format: uuid
        network_asset_id:
          $ref: "#/components/schemas/NetworkAssetId"
        asset_name:
          type: string
        symbol:
          type: string
        network:
          type: string
        network_standard:
          type: string
        address:
          type: string
        label:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        archived_at:
          type: [string, "null"]
          format: date-time
        projects:
          type: array
          description: |
            Present on `GET /v1/account/wallets`: the projects this wallet
            receives for, limited to the projects the key can reach.
          items:
            type: object
            required: [id, name, slug, route_id, is_default]
            properties:
              id:
                type: string
                format: uuid
              name:
                type: string
              slug:
                type: string
              route_id:
                type: string
                format: uuid
              is_default:
                type: boolean
    AccountOverview:
      type: object
      required: [owner_id, key, networks, wallets, project_count]
      properties:
        owner_id:
          type: string
          format: uuid
        key:
          $ref: "#/components/schemas/AccountAgentKeyInfo"
        networks:
          type: array
          items:
            $ref: "#/components/schemas/AccountNetwork"
        wallets:
          type: [array, "null"]
          description: Null unless the key holds wallets:read.
          items:
            $ref: "#/components/schemas/AccountWallet"
        project_count:
          type: integer
        api_base_url:
          type: [string, "null"]
          format: uri
        checkout_base_url:
          type: [string, "null"]
          format: uri
    AccountCreatedProject:
      type: object
      required: [id, name, slug, status]
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        slug:
          type: string
        status:
          type: string
          enum: [active, disabled]
        payer_receipts_enabled:
          type: boolean
          description: Returned by the update. True when payers get a receipt email.
        created_at:
          type: string
          format: date-time
    AccountProject:
      type: object
      required:
        [
          id,
          name,
          slug,
          status,
          payer_receipts_enabled,
          wallets,
          webhook,
          active_api_keys,
        ]
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        slug:
          type: string
        status:
          type: string
          enum: [active, disabled]
        payer_receipts_enabled:
          type: boolean
          description: True when payers whose invoice carries customer.email get a receipt email once it is paid.
        created_at:
          type: string
          format: date-time
        wallets:
          type: array
          items:
            type: object
            required: [network_asset_id, wallet_id, route_id, is_default]
            properties:
              network_asset_id:
                $ref: "#/components/schemas/NetworkAssetId"
              wallet_id:
                type: [string, "null"]
                format: uuid
              receiving_address:
                type: string
                description: Present only when the key holds wallets:read.
              route_id:
                type: string
                format: uuid
                description: Use as payment_route_id when creating invoices.
              is_default:
                type: boolean
        webhook:
          type: [object, "null"]
          properties:
            id:
              type: string
              format: uuid
            url:
              type: string
            status:
              type: string
        active_api_keys:
          type: integer
    ProjectWalletAssignment:
      type: object
      required: [changed, network_asset_id, wallet_id, route]
      properties:
        changed:
          type: boolean
        network_asset_id:
          $ref: "#/components/schemas/NetworkAssetId"
        wallet_id:
          type: [string, "null"]
          format: uuid
        route:
          type: [object, "null"]
          additionalProperties: true
          properties:
            id:
              type: string
              format: uuid
            receiving_address:
              type: string
              description: Present only when the key holds wallets:read.
            status:
              type: string
            is_default:
              type: boolean
    CreatedProjectKey:
      type: object
      required:
        [
          id,
          project_id,
          prefix,
          label,
          environment,
          scopes,
          api_key,
          created_at,
        ]
      properties:
        id:
          type: string
          format: uuid
        project_id:
          type: string
          format: uuid
        prefix:
          type: string
        label:
          type: string
        environment:
          type: string
          enum: [live, test]
        scopes:
          type: array
          items:
            type: string
            enum: [invoices:read, invoices:write]
        api_key:
          type: string
          description: Raw project key, shown once. Store it as NBTA_API_KEY.
        created_at:
          type: string
          format: date-time
    CreatedWebhookEndpoint:
      type: object
      required: [id, project_id, url, status, signing_secret]
      properties:
        id:
          type: string
          format: uuid
        project_id:
          type: string
          format: uuid
        url:
          type: string
        status:
          type: string
        signing_secret:
          type: string
          description: Signing secret, shown once. Store it as NBTA_WEBHOOK_SECRET.
        updated_at:
          type: string
          format: date-time
    WebhookStatus:
      type: object
      required:
        [
          project_id,
          configured,
          url,
          status,
          events,
          earliest_held_until,
          last_attempt,
        ]
      properties:
        project_id:
          type: string
          format: uuid
        configured:
          type: boolean
          description: True when the project has a webhook endpoint.
        endpoint_id:
          type: [string, "null"]
          format: uuid
        url:
          type: [string, "null"]
          description: The stored endpoint URL, as the project list reports it.
        status:
          type: [string, "null"]
          enum: [active, disabled, null]
          description: Endpoint status. `disabled` after a `410` answer.
        events:
          type: object
          required: [pending, processing, held, expired, dead, delivered_7d]
          properties:
            pending:
              type: integer
            processing:
              type: integer
            held:
              type: integer
              description: Parked for up to 7 days after a `410`; replayed when a new endpoint is saved.
            expired:
              type: integer
              description: Held events whose hold ended. Never deleted.
            dead:
              type: integer
            delivered_7d:
              type: integer
              description: Delivered in the last 7 days.
        earliest_held_until:
          type: [string, "null"]
          format: date-time
          description: When the soonest held event expires, or null.
        last_attempt:
          type: [object, "null"]
          description: The latest delivery attempt across the project, or null.
          required: [attempted_at, http_status, error_code]
          properties:
            attempted_at:
              type: string
              format: date-time
            http_status:
              type: [integer, "null"]
            error_code:
              type: [string, "null"]
              description: Coarse class such as `http_4xx`, `http_5xx`, `http_429` or `delivery_failed`; null on success.
    AccountSetupRequest:
      type: object
      additionalProperties: false
      required: [name]
      properties:
        name:
          type: string
          minLength: 2
          maxLength: 80
        slug:
          $ref: "#/components/schemas/ProjectSlug"
        site_url:
          type: string
          format: uri
          pattern: ^https://
          description: The store's public URL. Used to derive the slug when none is sent.
        webhook_url:
          type: string
          format: uri
          pattern: ^https://
          maxLength: 2048
        networks:
          type: array
          maxItems: 10
          items:
            $ref: "#/components/schemas/NetworkAssetId"
        wallet_ids:
          type: array
          maxItems: 10
          description: One chosen wallet per network, from a previous wallet_selection_required answer.
          items:
            type: string
            format: uuid
        key_label:
          type: string
          minLength: 2
          maxLength: 80
          description: Label of the issued project key. Defaults to "Agent setup".
        rotate_key:
          type: boolean
          description: |
            Issue a new project key for an existing project. Only pass it when
            the stored key is lost; the previous key stays active until the
            owner revokes it.
        rotate_webhook:
          type: boolean
          description: |
            Rotate the webhook signing secret even when the URL is unchanged.
            Requires `webhooks:write`. The previous secret stays valid for one
            hour.
    WalletSelection:
      type: object
      required: [network_asset_id, reason, choices]
      properties:
        network_asset_id:
          $ref: "#/components/schemas/NetworkAssetId"
        reason:
          type: string
          enum: [no_wallet, multiple_wallets]
        choices:
          type: array
          items:
            type: object
            required: [id, label, address]
            properties:
              id:
                type: string
                format: uuid
              label:
                type: string
              address:
                type: string
    AccountSetupResult:
      type: object
      required: [status, project, wallets, key_created, api_key, webhook, env]
      properties:
        status:
          type: string
          const: ready
        key_created:
          type: boolean
          description: |
            True when this call issued a project key; `api_key.api_key` then
            holds it, once. False when the project already had an active live
            key and `rotate_key` was not set: `api_key` then describes that
            key without its secret.
        project:
          type: object
          required: [id, name, slug, status, created]
          properties:
            id:
              type: string
              format: uuid
            name:
              type: string
            slug:
              type: string
            status:
              type: string
            created:
              type: boolean
        wallets:
          type: array
          items:
            type: object
            required: [network_asset_id, wallet_id, route_id, changed]
            properties:
              network_asset_id:
                $ref: "#/components/schemas/NetworkAssetId"
              wallet_id:
                type: string
                format: uuid
              receiving_address:
                type: string
                description: Present only when the key holds wallets:read.
              route_id:
                type: string
                format: uuid
                description: Use as payment_route_id when creating invoices.
              changed:
                type: boolean
        api_key:
          type: object
          required: [prefix]
          properties:
            id:
              type: string
              format: uuid
            prefix:
              type: string
            label:
              type: string
            environment:
              type: string
              enum: [live, test]
            scopes:
              type: array
              items:
                type: string
            api_key:
              type: string
              description: Raw project key, present only when key_created is true.
            project_id:
              type: string
              format: uuid
            created_at:
              type: string
              format: date-time
        webhook:
          type: [object, "null"]
          properties:
            id:
              type: string
              format: uuid
            url:
              type: string
            status:
              type: string
            signing_secret:
              type: string
              description: Present only when this call created or changed the endpoint (changed is true).
            changed:
              type: boolean
              description: |
                True when this call created the endpoint, changed its URL,
                re-activated it or rotated its secret.
            project_id:
              type: string
              format: uuid
            updated_at:
              type: string
              format: date-time
        site_url:
          type: [string, "null"]
        api_base_url:
          type: [string, "null"]
        checkout_base_url:
          type: [string, "null"]
        env:
          type: string
          description: |
            Ready .env lines: NBTA_API_URL, plus NBTA_API_KEY and
            NBTA_WEBHOOK_SECRET when this call returned them.
    Problem:
      type: object
      additionalProperties: false
      required: [type, title, status, code, detail, request_id]
      properties:
        type:
          type: string
          format: uri
        title:
          type: string
        status:
          type: integer
          minimum: 400
          maximum: 599
        code:
          type: string
        detail:
          type: string
        request_id:
          type: string
          format: uuid
        selections:
          type: array
          description: Present on wallet_selection_required only.
          items:
            $ref: "#/components/schemas/WalletSelection"
