Add stablecoin direct mint/burn issuance API surface

openapi/components/schemas/errors/Error503.yaml

@@ -0,0 +1,26 @@
+type: object
+required:
+  - message
+  - status
+  - code
+properties:
+  status:
+    type: integer
+    enum:
+      - 503
+    description: HTTP status code
+  code:
+    type: string
+    description: |
+      | Error Code | Description |
+      |------------|-------------|
+      | SERVICE_UNAVAILABLE | Downstream service is temporarily unavailable |
+    enum:
+      - SERVICE_UNAVAILABLE
+  message:
+    type: string
+    description: Error message
+  details:
+    type: object
+    description: Additional error details
+    additionalProperties: true

openapi/components/schemas/stablecoins/Stablecoin.yaml

@@ -0,0 +1,74 @@
+type: object
+required:
+  - id
+  - name
+  - symbol
+  - baseCurrency
+  - network
+  - decimals
+  - issuanceStatus
+  - gridOperationsStatus
+  - networkTokenIdentifier
+  - provider
+  - stablecoinProviderAccountId
+  - providerEnvironment
+  - providerTokenIdentifier
+  - createdAt
+  - updatedAt
+properties:
+  id:
+    type: string
+    description: System-generated stablecoin identifier.
+    example: Stablecoin:019542f5-b3e7-1d02-0000-000000000002
+  name:
+    type: string
+    description: Stablecoin display name.
+    example: Acme Dollar
+  symbol:
+    type: string
+    description: Stablecoin symbol.
+    example: ACME
+  baseCurrency:
+    type: string
+    description: Fiat currency the stablecoin is denominated against.
+    example: USD
+  network:
+    $ref: StablecoinNetwork.yaml
+  decimals:
+    type: integer
+    description: Number of decimal places used by the stablecoin.
+    example: 6
+  issuanceStatus:
+    $ref: StablecoinIssuanceStatus.yaml
+  gridOperationsStatus:
+    $ref: StablecoinGridOperationsStatus.yaml
+  networkTokenIdentifier:
+    type: string
+    description: Token identifier in the namespace selected by `network`.
+    example: btkn1qw508d6qejxtdg4y5r3zarvary0c5xw7k
+  currency:
+    type: string
+    description: Grid currency code after the stablecoin is enabled for Grid operations.
+    example: ACME
+  provider:
+    $ref: StablecoinProvider.yaml
+  stablecoinProviderAccountId:
+    type: string
+    description: Stablecoin provider account link selected for this stablecoin.
+    example: StablecoinProviderAccount:019542f5-b3e7-1d02-0000-000000000001
+  providerEnvironment:
+    $ref: StablecoinProviderEnvironment.yaml
+  providerTokenIdentifier:
+    type: string
+    description: Provider token identifier. For Brale this maps to `value_type`.
+    example: ACME
+  createdAt:
+    type: string
+    format: date-time
+    description: Creation timestamp.
+    example: '2026-05-20T16:40:00Z'
+  updatedAt:
+    type: string
+    format: date-time
+    description: Last update timestamp.
+    example: '2026-05-20T17:10:00Z'

openapi/components/schemas/stablecoins/StablecoinAchDebitFundingSource.yaml

@@ -0,0 +1,19 @@
+title: ACH Debit
+allOf:
+  - $ref: ./StablecoinMintFundingSourceBase.yaml
+  - type: object
+    required:
+      - type
+      - externalAccountId
+    properties:
+      type:
+        type: string
+        enum:
+          - ACH_DEBIT
+        description: ACH debit funding.
+        example: ACH_DEBIT
+      externalAccountId:
+        type: string
+        description: Grid `ExternalAccount` debited to fund the mint.
+        example: ExternalAccount:019542f5-b3e7-1d02-0000-000000000101
+    description: ACH debit funding source. The provider debits the referenced external account.

openapi/components/schemas/stablecoins/StablecoinBurnDestination.yaml

@@ -0,0 +1,23 @@
+type: object
+required:
+  - type
+  - externalAccountId
+  - rail
+properties:
+  type:
+    type: string
+    enum:
+      - EXTERNAL_ACCOUNT
+    description: Burn destination variant. V1 supports fiat Grid `ExternalAccount` destinations.
+  externalAccountId:
+    type: string
+    description: Grid bank `ExternalAccount` receiving fiat redemption proceeds.
+    example: ExternalAccount:019542f5-b3e7-1d02-0000-000000000205
+  rail:
+    type: string
+    enum:
+      - WIRE
+      - ACH_CREDIT
+      - SAME_DAY_ACH_CREDIT
+      - RTP_CREDIT
+    description: Fiat payout rail for the burn destination.

openapi/components/schemas/stablecoins/StablecoinBurnRequest.yaml

@@ -0,0 +1,20 @@
+type: object
+required:
+  - amount
+  - source
+  - destination
+properties:
+  amount:
+    type: string
+    pattern: '^[0-9]+$'
+    description: Amount to burn in the stablecoin's smallest unit. The amount must convert exactly to a whole fiat cent for the token decimals.
+    example: '1000000'
+  source:
+    $ref: StablecoinBurnSource.yaml
+  destination:
+    $ref: StablecoinBurnDestination.yaml
+  description:
+    type: string
+    maxLength: 1024
+    description: Optional platform-provided operation description.
+    example: Redeem ACME

openapi/components/schemas/stablecoins/StablecoinBurnSource.yaml

@@ -0,0 +1,10 @@
+oneOf:
+  - $ref: ./StablecoinExternalAccountBurnSource.yaml
+  - $ref: ./StablecoinGridInternalBurnSource.yaml
+  - $ref: ./StablecoinProviderBalanceBurnSource.yaml
+discriminator:
+  propertyName: type
+  mapping:
+    EXTERNAL_ACCOUNT: ./StablecoinExternalAccountBurnSource.yaml
+    GRID_INTERNAL_ACCOUNT: ./StablecoinGridInternalBurnSource.yaml
+    PROVIDER_INTERNAL_BALANCE: ./StablecoinProviderBalanceBurnSource.yaml

openapi/components/schemas/stablecoins/StablecoinBurnSourceBase.yaml

@@ -0,0 +1,12 @@
+type: object
+required:
+  - type
+properties:
+  type:
+    type: string
+    enum:
+      - EXTERNAL_ACCOUNT
+      - GRID_INTERNAL_ACCOUNT
+      - PROVIDER_INTERNAL_BALANCE
+    description: Burn source variant. Grid internal account burns are reserved for the Grid-enabled ledger movement flow.
+    example: EXTERNAL_ACCOUNT

openapi/components/schemas/stablecoins/StablecoinEstimatedDelivery.yaml

@@ -0,0 +1,26 @@
+type: object
+description: Static rail timing estimate for fiat redemption delivery. This is guidance, not a guaranteed arrival time.
+additionalProperties: true
+properties:
+  rail:
+    type: string
+    description: Fiat payout rail the estimate applies to.
+    example: ACH_CREDIT
+  amount:
+    type: string
+    pattern: '^[0-9]+$'
+    description: Estimated delivery amount in the smallest unit of `currency` (e.g. cents for USD).
+    example: '100'
+  currency:
+    type: string
+    description: ISO 4217 currency code of the fiat payout.
+    example: USD
+  timing:
+    type: string
+    description: Human-readable rail timing estimate.
+    example: 1-3 business days
+example:
+  rail: ACH_CREDIT
+  amount: '100'
+  currency: USD
+  timing: 1-3 business days

openapi/components/schemas/stablecoins/StablecoinExternalAccountBurnSource.yaml

@@ -0,0 +1,19 @@
+title: External Account
+allOf:
+  - $ref: ./StablecoinBurnSourceBase.yaml
+  - type: object
+    required:
+      - type
+      - externalAccountId
+    properties:
+      type:
+        type: string
+        enum:
+          - EXTERNAL_ACCOUNT
+        description: External account burn. References an active Spark external account and returns funding instructions.
+        example: EXTERNAL_ACCOUNT
+      externalAccountId:
+        type: string
+        description: Grid Spark `ExternalAccount` expected to fund the provider for the burn.
+        example: ExternalAccount:019542f5-b3e7-1d02-0000-000000000203
+    description: External account burn source. The issuer funds the provider from a Spark external account.

openapi/components/schemas/stablecoins/StablecoinFundingInstructions.yaml

@@ -0,0 +1,32 @@
+type: object
+description: >-
+  Provider funding instructions safe to show publicly. Present for wire-funded
+  mint operations and external-source burn operations when available. The common
+  fields below are always declared; the exact set of remaining fields is
+  rail- and provider-specific (for example, wire instructions carry bank
+  beneficiary/account/routing details while Spark and on-chain instructions
+  carry a deposit address), so `additionalProperties` stays open to pass those
+  through without a spec change per rail.
+additionalProperties: true
+properties:
+  rail:
+    type: string
+    description: Funding rail these instructions apply to (e.g. `SPARK`, `WIRE`).
+    example: SPARK
+  network:
+    type: string
+    description: Network the funds should be sent on, when applicable.
+    example: SPARK
+  address:
+    type: string
+    description: Deposit address the issuer sends funds to, for on-chain or Spark rails.
+    example: spark1...
+  valueType:
+    type: string
+    description: Provider token/value type the deposit address expects.
+    example: ACME
+example:
+  rail: SPARK
+  network: SPARK
+  address: spark1...
+  valueType: ACME

openapi/components/schemas/stablecoins/StablecoinGridInternalBurnSource.yaml

@@ -0,0 +1,19 @@
+title: Grid Internal Account
+allOf:
+  - $ref: ./StablecoinBurnSourceBase.yaml
+  - type: object
+    required:
+      - type
+      - accountId
+    properties:
+      type:
+        type: string
+        enum:
+          - GRID_INTERNAL_ACCOUNT
+        description: Grid internal account burn. Reserved for the Grid-controlled ledger movement flow.
+        example: GRID_INTERNAL_ACCOUNT
+      accountId:
+        type: string
+        description: Grid internal source account id.
+        example: InternalAccount:019542f5-b3e7-1d02-0000-000000000204
+    description: Grid internal account burn source, reserved for future Grid-controlled burn flows.

openapi/components/schemas/stablecoins/StablecoinGridInternalFundingSource.yaml

@@ -0,0 +1,19 @@
+title: Grid Internal Account
+allOf:
+  - $ref: ./StablecoinMintFundingSourceBase.yaml
+  - type: object
+    required:
+      - type
+      - accountId
+    properties:
+      type:
+        type: string
+        enum:
+          - GRID_INTERNAL_ACCOUNT
+        description: Grid internal account funding. Reserved for the follow-up Grid-funded mint flow.
+        example: GRID_INTERNAL_ACCOUNT
+      accountId:
+        type: string
+        description: Grid internal funding account id.
+        example: InternalAccount:019542f5-b3e7-1d02-0000-000000000102
+    description: Grid internal account funding source, reserved for future Grid-funded mint flows.

openapi/components/schemas/stablecoins/StablecoinGridOperationsStatus.yaml

@@ -0,0 +1,8 @@
+type: string
+enum:
+  - NOT_ENABLED
+  - PENDING_APPROVAL
+  - ENABLING
+  - ENABLED
+  - DISABLED
+description: Whether the stablecoin has been enabled for normal Grid operations.

openapi/components/schemas/stablecoins/StablecoinIssuanceStatus.yaml

@@ -0,0 +1,8 @@
+type: string
+enum:
+  - PENDING_REVIEW
+  - PROVISIONING
+  - PROVISIONED
+  - REJECTED
+  - FAILED
+description: Provider issuance/linking status for the registered stablecoin.

openapi/components/schemas/stablecoins/StablecoinListResponse.yaml

@@ -0,0 +1,18 @@
+type: object
+required:
+  - data
+  - hasMore
+properties:
+  data:
+    type: array
+    items:
+      $ref: Stablecoin.yaml
+  hasMore:
+    type: boolean
+    description: Indicates if more results are available beyond this page.
+  nextCursor:
+    type: string
+    description: Cursor to retrieve the next page of results.
+  totalCount:
+    type: integer
+    description: Total number of stablecoins matching the criteria.

openapi/components/schemas/stablecoins/StablecoinMintDestination.yaml

@@ -0,0 +1,18 @@
+type: object
+description: >-
+  Account that receives the minted stablecoin. External and Grid-managed
+  accounts are represented as a single account reference, matching the
+  `accountId` pattern used elsewhere in the API; the id prefix
+  (`ExternalAccount:` or `InternalAccount:`) determines which. In the
+  initial Brale-backed flow this must reference an active Spark external
+  account.
+required:
+  - accountId
+properties:
+  accountId:
+    type: string
+    description: >-
+      Grid account receiving the minted stablecoin. Accepts an
+      `ExternalAccount:` id (initial Brale-backed flow) or an
+      `InternalAccount:` id for Grid-managed destinations.
+    example: ExternalAccount:019542f5-b3e7-1d02-0000-000000000201

openapi/components/schemas/stablecoins/StablecoinMintFundingSource.yaml

@@ -0,0 +1,14 @@
+oneOf:
+  - $ref: ./StablecoinWireFundingSource.yaml
+  - $ref: ./StablecoinAchDebitFundingSource.yaml
+  - $ref: ./StablecoinSameDayAchDebitFundingSource.yaml
+  - $ref: ./StablecoinGridInternalFundingSource.yaml
+  - $ref: ./StablecoinProviderBalanceFundingSource.yaml
+discriminator:
+  propertyName: type
+  mapping:
+    WIRE: ./StablecoinWireFundingSource.yaml
+    ACH_DEBIT: ./StablecoinAchDebitFundingSource.yaml
+    SAME_DAY_ACH_DEBIT: ./StablecoinSameDayAchDebitFundingSource.yaml
+    GRID_INTERNAL_ACCOUNT: ./StablecoinGridInternalFundingSource.yaml
+    PROVIDER_INTERNAL_BALANCE: ./StablecoinProviderBalanceFundingSource.yaml

openapi/components/schemas/stablecoins/StablecoinMintFundingSourceBase.yaml

@@ -0,0 +1,14 @@
+type: object
+required:
+  - type
+properties:
+  type:
+    type: string
+    enum:
+      - WIRE
+      - ACH_DEBIT
+      - SAME_DAY_ACH_DEBIT
+      - GRID_INTERNAL_ACCOUNT
+      - PROVIDER_INTERNAL_BALANCE
+    description: Funding source variant. Grid internal account and provider internal balance funding are reserved for follow-up support.
+    example: ACH_DEBIT