openapi.yaml

openapi: 3.1.0
info:
  title: SetOff clearing service
  version: "1"
  description: |
    Participants record what they owe each other into the open settlement
    window. Closing a window nets it multilaterally, archives it, and opens
    the next. Amounts are integers in each asset's smallest unit, as strings.
  license:
    name: Apache-2.0
    identifier: Apache-2.0
servers:
  - url: http://127.0.0.1:7500
security:
  - participant: []
  - operator: []
paths:
  /healthz:
    get:
      summary: Liveness
      security: []
      responses:
        "200":
          description: The process is up.
  /metrics:
    get:
      summary: Prometheus counters by route pattern and status
      security: []
      responses:
        "200":
          description: Prometheus text exposition format.
          content:
            text/plain: {}
  /auth:
    get:
      summary: SEP-10 challenge for a participant's Stellar account
      description: Present when the service is configured with [sep10].
      security: []
      parameters:
        - { name: account, in: query, required: true, schema: { type: string }, description: The participant's G… account. }
      responses:
        "200":
          description: A challenge transaction to sign with the account's key.
          content:
            application/json:
              schema:
                type: object
                properties:
                  transaction: { type: string, description: base64 XDR }
                  network_passphrase: { type: string }
        "400": { $ref: "#/components/responses/Error" }
    post:
      summary: Exchange a signed challenge for a bearer token
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [transaction]
              properties:
                transaction: { type: string, description: The challenge, signed by the account. }
      responses:
        "200":
          description: A bearer token valid for one hour.
          content:
            application/json:
              schema:
                type: object
                properties:
                  token: { type: string }
        "400": { $ref: "#/components/responses/Error" }
        "403":
          description: The account belongs to no participant.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
  /.well-known/stellar.toml:
    get:
      summary: SEP-1 file naming the web auth endpoint and signing key
      security: []
      responses:
        "200":
          description: TOML with WEB_AUTH_ENDPOINT, SIGNING_KEY and NETWORK_PASSPHRASE.
          content:
            text/plain: {}
  /v1/obligations:
    post:
      summary: Record an obligation the caller owes
      description: The debtor is always the caller; nobody can commit someone else to pay.
      security:
        - participant: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [reference, creditor, asset, amount]
              properties:
                reference: { type: string, minLength: 1, maxLength: 64, description: Unique per debtor within a window. }
                creditor: { type: string, description: Participant id. }
                asset: { type: string }
                amount: { $ref: "#/components/schemas/Amount" }
      responses:
        "201":
          description: Recorded and fsynced.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id: { type: string, description: "<debtor>:<reference>" }
                  window: { type: integer }
        "200":
          description: "An identical obligation was already recorded under this reference: its id is returned, with replayed set to true."
          content:
            application/json:
              schema:
                type: object
                properties:
                  id: { type: string }
                  window: { type: integer }
                  replayed: { type: boolean, const: true }
        "400": { $ref: "#/components/responses/Error" }
        "401": { $ref: "#/components/responses/Error" }
        "409":
          description: The reference was already used in this window for a different obligation.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
  /v1/window:
    get:
      summary: The open window, netted live
      responses:
        "200":
          description: Window number, obligation count and netting.
          content:
            application/json:
              schema:
                type: object
                properties:
                  window: { type: integer }
                  obligations: { type: integer }
                  netting: { $ref: "#/components/schemas/Netting" }
        "401": { $ref: "#/components/responses/Error" }
  /v1/me:
    get:
      summary: The caller's side of the open window
      security:
        - participant: []
      responses:
        "200":
          description: Obligations owed by or to the caller, its net positions, and the plan legs it pays or receives.
          content:
            application/json:
              schema:
                type: object
                properties:
                  window: { type: integer }
                  obligations: { type: array, items: { $ref: "#/components/schemas/Obligation" } }
                  positions: { type: array, items: { $ref: "#/components/schemas/Position" } }
                  transfers: { type: array, items: { $ref: "#/components/schemas/Transfer" } }
        "401": { $ref: "#/components/responses/Error" }
  /v1/window/close:
    post:
      summary: Net, archive and open the next window
      security:
        - operator: []
      responses:
        "200":
          description: The closed window.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Closed" }
        "401": { $ref: "#/components/responses/Error" }
  /v1/windows:
    get:
      summary: Archived windows, newest first
      parameters:
        - { name: before, in: query, schema: { type: integer }, description: Only windows numbered below this. }
        - { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 500, default: 50 } }
      responses:
        "200":
          description: Window summaries.
          content:
            application/json:
              schema:
                type: object
                properties:
                  windows:
                    type: array
                    items:
                      type: object
                      properties:
                        window: { type: integer }
                        closed_at: { type: string, format: date-time }
                        obligations: { type: integer }
                        transfers: { type: integer }
        "400": { $ref: "#/components/responses/Error" }
        "401": { $ref: "#/components/responses/Error" }
  /v1/windows/{n}:
    get:
      summary: An archived window
      parameters:
        - { name: n, in: path, required: true, schema: { type: integer } }
      responses:
        "200":
          description: The window as closed.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Closed" }
        "401": { $ref: "#/components/responses/Error" }
        "404": { $ref: "#/components/responses/Error" }
  /v1/windows/{n}/camt053:
    get:
      summary: ISO 20022 camt.053 statements for an archived window
      description: |
        One statement per participant and asset. Participants receive only
        their own statements; the operator receives all of them.
      parameters:
        - { name: n, in: path, required: true, schema: { type: integer } }
      responses:
        "200":
          description: A camt.053.001.08 BankToCustomerStatement document.
          content:
            application/xml: {}
        "401": { $ref: "#/components/responses/Error" }
        "404": { $ref: "#/components/responses/Error" }
  /v1/windows/{n}/settlement:
    post:
      summary: Prepare on-chain settlement of a closed window
      description: |
        Simulates each `submit` batch of the window's plan against the
        settlement contract and records the Soroban authorization entries its
        debtors must sign, valid for `validity_ledgers`. Preparing again
        refreshes batches not yet submitted, with new nonces and expiry.
      security:
        - operator: []
      parameters:
        - { name: n, in: path, required: true, schema: { type: integer } }
      responses:
        "200":
          description: The settlement session.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Settlement" }
        "401": { $ref: "#/components/responses/Error" }
        "404": { $ref: "#/components/responses/Error" }
        "409": { $ref: "#/components/responses/Error" }
        "502": { $ref: "#/components/responses/Error" }
    get:
      summary: Settlement progress
      security:
        - participant: []
        - operator: []
      parameters:
        - { name: n, in: path, required: true, schema: { type: integer } }
      responses:
        "200":
          description: The session, how many authorizations are still missing, and whether the window is settled.
          content:
            application/json:
              schema:
                type: object
                properties:
                  session: { $ref: "#/components/schemas/Settlement" }
                  pending: { type: integer }
                  settled: { type: boolean }
        "401": { $ref: "#/components/responses/Error" }
        "404": { $ref: "#/components/responses/Error" }
  /v1/windows/{n}/authorizations:
    get:
      summary: The caller's authorization entries to sign
      description: |
        Each entry authorizes one `submit` call on the debtor's behalf. Sign
        `hash` with the account's Ed25519 key, or sign `entry` with a Stellar
        SDK's `authorizeEntry` or tessera-coordinator's `/v1/authorize`.
      security:
        - participant: []
      parameters:
        - { name: n, in: path, required: true, schema: { type: integer } }
      responses:
        "200":
          description: Entries for the caller, in batches not yet settled.
          content:
            application/json:
              schema:
                type: object
                properties:
                  window: { type: integer }
                  address: { type: string }
                  authorizations:
                    type: array
                    items:
                      type: object
                      properties:
                        batch: { type: integer }
                        slot: { type: integer }
                        entry: { type: string, description: Unsigned base64 SorobanAuthorizationEntry. }
                        hash: { type: string, description: "SHA-256 of the entry's HashIdPreimage on this network, hex: what an Ed25519 key signs." }
                        expiration_ledger: { type: integer }
                        signed: { type: boolean }
        "401": { $ref: "#/components/responses/Error" }
        "404": { $ref: "#/components/responses/Error" }
        "409": { $ref: "#/components/responses/Error" }
    post:
      summary: Hand back signed authorization entries
      description: |
        Each item names its batch and slot and carries either the whole signed
        entry or, for a G… account, the hex Ed25519 signature of its `hash`.
        A signed entry must equal the issued one except for its signature, and
        account signatures are verified before anything is recorded; one bad
        item rejects the request. Once every entry of a batch is signed, the
        service submits it, then calls `settle` after the last batch.
      security:
        - participant: []
      parameters:
        - { name: n, in: path, required: true, schema: { type: integer } }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [authorizations]
              properties:
                authorizations:
                  type: array
                  items:
                    type: object
                    required: [batch, slot]
                    properties:
                      batch: { type: integer }
                      slot: { type: integer }
                      entry: { type: string }
                      signature: { type: string }
      responses:
        "202":
          description: Recorded; submission, if due, runs in the background.
          content:
            application/json:
              schema:
                type: object
                properties:
                  window: { type: integer }
                  accepted: { type: integer }
                  pending: { type: integer }
        "400": { $ref: "#/components/responses/Error" }
        "401": { $ref: "#/components/responses/Error" }
        "404": { $ref: "#/components/responses/Error" }
        "422": { $ref: "#/components/responses/Error" }
components:
  securitySchemes:
    participant:
      type: http
      scheme: bearer
      description: A participant's key, from its key_env, or a SEP-10 token from POST /auth.
    operator:
      type: http
      scheme: bearer
      description: The operator's key, from operator_key_env.
  schemas:
    Amount:
      type: string
      pattern: "^[1-9][0-9]*$"
      description: A positive integer in the asset's smallest unit.
    Obligation:
      type: object
      properties:
        id: { type: string }
        debtor: { type: string }
        creditor: { type: string }
        asset: { type: string }
        amount: { $ref: "#/components/schemas/Amount" }
    Position:
      type: object
      properties:
        asset: { type: string }
        participant: { type: string }
        net: { type: string, description: Positive receives, negative pays. }
    Transfer:
      type: object
      properties:
        asset: { type: string }
        from: { type: string }
        to: { type: string }
        amount: { $ref: "#/components/schemas/Amount" }
    Netting:
      type: object
      properties:
        positions: { type: array, items: { $ref: "#/components/schemas/Position" } }
        transfers: { type: array, items: { $ref: "#/components/schemas/Transfer" } }
        assets:
          type: array
          items:
            type: object
            properties:
              asset: { type: string }
              obligations: { type: integer }
              gross: { type: string }
              settled: { type: string }
              transfers: { type: integer }
    Closed:
      type: object
      properties:
        window: { type: integer }
        closed_at: { type: string, format: date-time }
        obligations: { type: array, items: { $ref: "#/components/schemas/Obligation" } }
        netting: { $ref: "#/components/schemas/Netting" }
    Tx:
      type: object
      properties:
        hash: { type: string }
        status: { type: string, enum: [SUCCESS, FAILED, REJECTED], description: "REJECTED: refused in simulation, never sent." }
        ledger: { type: integer }
        error: { type: string }
    Settlement:
      type: object
      properties:
        window: { type: integer }
        contract: { type: string }
        batches:
          type: array
          items:
            type: object
            properties:
              obligations: { type: array, items: { type: object } }
              auth: { type: array, items: { type: string } }
              entries: { type: array, items: { type: object } }
              tx: { $ref: "#/components/schemas/Tx" }
        settle: { $ref: "#/components/schemas/Tx" }
    Error:
      type: object
      required: [error]
      properties:
        error: { type: string }
  responses:
    Error:
      description: See `error`.
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }