From 5c020e33e1e69bb2d829a93288942cf444a0bb3a Mon Sep 17 00:00:00 2001 From: kphurley7 Date: Tue, 14 Jul 2026 12:40:58 -0500 Subject: [PATCH 1/3] Add stablecoin direct mint/burn issuance API surface Adds the public API surface for direct stablecoin issuer operations that shipped in the Grid server (webdev #29077 mint, #29078 burn): register a provider-created stablecoin, list/get stablecoins, create direct mint and burn operations, and list/get the resulting issuer operations. - New paths: /stablecoins, /stablecoins/{id}, /stablecoins/{id}/mints, /stablecoins/{id}/burns, /stablecoins/{id}/operations, /stablecoin-operations/{id}. - New schemas under components/schemas/stablecoins: Stablecoin, StablecoinListResponse, StablecoinRegisterRequest, StablecoinMintRequest, StablecoinBurnRequest, mint/burn source+destination, StablecoinOperation, StablecoinOperation{Type,Status,Destination,ListResponse}, StablecoinFundingInstructions, StablecoinEstimatedDelivery, StablecoinNetwork, Stablecoin{Grid,}OperationsStatus, StablecoinIssuanceStatus. - Adds Error503 (SERVICE_UNAVAILABLE) used by the issuance responses. StablecoinOperation.destination is a single merged StablecoinOperationDestination object (superset of the mint/burn request destinations), NOT a oneOf: a non-discriminated oneOf[Mint,Burn] is ambiguous (a burn destination validates as both variants), so the generated SDK raises "Multiple matches found" on every burn operation response. The merged object deserializes unambiguously. This supersedes the quote-based issuance design in #578 (which is being closed); the shipped server implements direct operations, not quotes. Bundled with redocly; `redocly lint` passes. Co-Authored-By: Claude Fable 5 --- mintlify/openapi.yaml | 881 +++++++++++++++++- openapi.yaml | 881 +++++++++++++++++- .../components/schemas/errors/Error503.yaml | 26 + .../schemas/stablecoins/Stablecoin.yaml | 74 ++ .../StablecoinBurnDestination.yaml | 23 + .../stablecoins/StablecoinBurnRequest.yaml | 20 + .../stablecoins/StablecoinBurnSource.yaml | 19 + .../StablecoinEstimatedDelivery.yaml | 8 + .../StablecoinFundingInstructions.yaml | 8 + .../StablecoinGridOperationsStatus.yaml | 8 + .../stablecoins/StablecoinIssuanceStatus.yaml | 8 + .../stablecoins/StablecoinListResponse.yaml | 18 + .../StablecoinMintDestination.yaml | 18 + .../StablecoinMintFundingSource.yaml | 29 + .../stablecoins/StablecoinMintRequest.yaml | 20 + .../stablecoins/StablecoinNetwork.yaml | 4 + .../stablecoins/StablecoinOperation.yaml | 74 ++ .../StablecoinOperationDestination.yaml | 33 + .../StablecoinOperationListResponse.yaml | 18 + .../StablecoinOperationStatus.yaml | 10 + .../stablecoins/StablecoinOperationType.yaml | 5 + .../StablecoinRegisterRequest.yaml | 20 + openapi/openapi.yaml | 16 +- ...in-operations_{stablecoinOperationId}.yaml | 40 + openapi/paths/stablecoins/stablecoins.yaml | 124 +++ .../stablecoins_{stablecoinId}.yaml | 40 + .../stablecoins_{stablecoinId}_burns.yaml | 73 ++ .../stablecoins_{stablecoinId}_mints.yaml | 73 ++ ...stablecoins_{stablecoinId}_operations.yaml | 56 ++ 29 files changed, 2613 insertions(+), 14 deletions(-) create mode 100644 openapi/components/schemas/errors/Error503.yaml create mode 100644 openapi/components/schemas/stablecoins/Stablecoin.yaml create mode 100644 openapi/components/schemas/stablecoins/StablecoinBurnDestination.yaml create mode 100644 openapi/components/schemas/stablecoins/StablecoinBurnRequest.yaml create mode 100644 openapi/components/schemas/stablecoins/StablecoinBurnSource.yaml create mode 100644 openapi/components/schemas/stablecoins/StablecoinEstimatedDelivery.yaml create mode 100644 openapi/components/schemas/stablecoins/StablecoinFundingInstructions.yaml create mode 100644 openapi/components/schemas/stablecoins/StablecoinGridOperationsStatus.yaml create mode 100644 openapi/components/schemas/stablecoins/StablecoinIssuanceStatus.yaml create mode 100644 openapi/components/schemas/stablecoins/StablecoinListResponse.yaml create mode 100644 openapi/components/schemas/stablecoins/StablecoinMintDestination.yaml create mode 100644 openapi/components/schemas/stablecoins/StablecoinMintFundingSource.yaml create mode 100644 openapi/components/schemas/stablecoins/StablecoinMintRequest.yaml create mode 100644 openapi/components/schemas/stablecoins/StablecoinNetwork.yaml create mode 100644 openapi/components/schemas/stablecoins/StablecoinOperation.yaml create mode 100644 openapi/components/schemas/stablecoins/StablecoinOperationDestination.yaml create mode 100644 openapi/components/schemas/stablecoins/StablecoinOperationListResponse.yaml create mode 100644 openapi/components/schemas/stablecoins/StablecoinOperationStatus.yaml create mode 100644 openapi/components/schemas/stablecoins/StablecoinOperationType.yaml create mode 100644 openapi/components/schemas/stablecoins/StablecoinRegisterRequest.yaml create mode 100644 openapi/paths/stablecoins/stablecoin-operations_{stablecoinOperationId}.yaml create mode 100644 openapi/paths/stablecoins/stablecoins.yaml create mode 100644 openapi/paths/stablecoins/stablecoins_{stablecoinId}.yaml create mode 100644 openapi/paths/stablecoins/stablecoins_{stablecoinId}_burns.yaml create mode 100644 openapi/paths/stablecoins/stablecoins_{stablecoinId}_mints.yaml create mode 100644 openapi/paths/stablecoins/stablecoins_{stablecoinId}_operations.yaml diff --git a/mintlify/openapi.yaml b/mintlify/openapi.yaml index 476be1e8d..9671b1c24 100644 --- a/mintlify/openapi.yaml +++ b/mintlify/openapi.yaml @@ -58,7 +58,7 @@ tags: - name: Cards description: Card management endpoints. Issue debit cards against an internal account, freeze / unfreeze, close, manage card funding sources, and list card transactions. - name: Stablecoins - description: Stablecoin issuance endpoints. Link provider accounts, register provider-created stablecoins, create mint/burn quotes, execute them, and track the resulting operations. + description: Stablecoin issuance endpoints. Link provider accounts, register provider-created stablecoins, create direct mint/burn issuer operations, and track operation status. paths: /config: get: @@ -7481,6 +7481,418 @@ paths: application/json: schema: $ref: '#/components/schemas/Error500' + /stablecoins: + post: + summary: Register an existing provider-created stablecoin + description: | + Register an existing provider-created stablecoin as a Grid `Stablecoin`. This endpoint links provider token metadata to Grid; it does not create the token with the provider. Grid derives the active provider account link from the authenticated platform, provider, and provider environment. + operationId: registerStablecoin + tags: + - Stablecoins + security: + - BasicAuth: [] + parameters: + - name: Idempotency-Key + in: header + description: Required idempotency key for retrying this request safely. + required: true + schema: + type: string + maxLength: 255 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/StablecoinRegisterRequest' + responses: + '201': + description: Stablecoin registered + content: + application/json: + schema: + $ref: '#/components/schemas/Stablecoin' + '400': + description: Bad request + content: + application/json: + schema: + $ref: '#/components/schemas/Error400' + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/Error401' + '404': + description: Referenced stablecoin provider account not found + content: + application/json: + schema: + $ref: '#/components/schemas/Error404' + '409': + description: Conflict + content: + application/json: + schema: + $ref: '#/components/schemas/Error409' + '500': + description: Internal service error + content: + application/json: + schema: + $ref: '#/components/schemas/Error500' + get: + summary: List stablecoins + description: Retrieve stablecoins registered to the authenticated platform. + operationId: listStablecoins + tags: + - Stablecoins + security: + - BasicAuth: [] + parameters: + - name: issuanceStatus + in: query + required: false + schema: + $ref: '#/components/schemas/StablecoinIssuanceStatus' + - name: gridOperationsStatus + in: query + required: false + schema: + $ref: '#/components/schemas/StablecoinGridOperationsStatus' + - name: provider + in: query + required: false + schema: + $ref: '#/components/schemas/StablecoinProvider' + - name: limit + in: query + description: Maximum number of results to return (default 20, max 100) + required: false + schema: + type: integer + minimum: 1 + maximum: 100 + default: 20 + - name: cursor + in: query + description: Opaque cursor returned as `nextCursor` from the previous response. + required: false + schema: + type: string + responses: + '200': + description: Successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/StablecoinListResponse' + '400': + description: Bad request - Invalid parameters + content: + application/json: + schema: + $ref: '#/components/schemas/Error400' + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/Error401' + '500': + description: Internal service error + content: + application/json: + schema: + $ref: '#/components/schemas/Error500' + /stablecoins/{stablecoinId}: + parameters: + - name: stablecoinId + in: path + description: System-generated stablecoin identifier + required: true + schema: + type: string + get: + summary: Get a stablecoin + description: Retrieve a single registered stablecoin by its Grid identifier. + operationId: getStablecoin + tags: + - Stablecoins + security: + - BasicAuth: [] + responses: + '200': + description: Successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/Stablecoin' + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/Error401' + '404': + description: Stablecoin not found + content: + application/json: + schema: + $ref: '#/components/schemas/Error404' + '500': + description: Internal service error + content: + application/json: + schema: + $ref: '#/components/schemas/Error500' + /stablecoins/{stablecoinId}/mints: + parameters: + - name: stablecoinId + in: path + description: System-generated stablecoin identifier + required: true + schema: + type: string + post: + summary: Create a stablecoin mint operation + description: | + Create a provider-backed mint operation for a registered stablecoin. Funding and destination accounts are normal Grid `ExternalAccount` objects; any provider-specific Brale address linkage is managed internally by Grid. Wire-funded mints return funding instructions and remain pending until the provider reports funds received. + operationId: createStablecoinMint + tags: + - Stablecoins + security: + - BasicAuth: [] + parameters: + - name: Idempotency-Key + in: header + description: Required idempotency key for retrying this mint request safely. + required: true + schema: + type: string + maxLength: 255 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/StablecoinMintRequest' + responses: + '201': + description: Mint operation created + content: + application/json: + schema: + $ref: '#/components/schemas/StablecoinOperation' + '400': + description: Bad request + content: + application/json: + schema: + $ref: '#/components/schemas/Error400' + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/Error401' + '404': + description: Stablecoin or referenced account not found + content: + application/json: + schema: + $ref: '#/components/schemas/Error404' + '409': + description: Conflict + content: + application/json: + schema: + $ref: '#/components/schemas/Error409' + '500': + description: Internal service error + content: + application/json: + schema: + $ref: '#/components/schemas/Error500' + '503': + description: Provider temporarily unavailable + content: + application/json: + schema: + $ref: '#/components/schemas/Error503' + /stablecoins/{stablecoinId}/burns: + parameters: + - name: stablecoinId + in: path + description: System-generated stablecoin identifier + required: true + schema: + type: string + post: + summary: Create a stablecoin burn operation + description: | + Create a provider-backed burn/redemption operation for a registered stablecoin. Burn sources and fiat destinations are normal Grid account objects; provider-specific Brale address ids are resolved and stored internally. External Spark wallet sources return funding instructions and remain pending until the provider reports funds received. + operationId: createStablecoinBurn + tags: + - Stablecoins + security: + - BasicAuth: [] + parameters: + - name: Idempotency-Key + in: header + description: Required idempotency key for retrying this burn request safely. + required: true + schema: + type: string + maxLength: 255 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/StablecoinBurnRequest' + responses: + '201': + description: Burn operation created + content: + application/json: + schema: + $ref: '#/components/schemas/StablecoinOperation' + '400': + description: Bad request + content: + application/json: + schema: + $ref: '#/components/schemas/Error400' + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/Error401' + '404': + description: Stablecoin or referenced account not found + content: + application/json: + schema: + $ref: '#/components/schemas/Error404' + '409': + description: Conflict + content: + application/json: + schema: + $ref: '#/components/schemas/Error409' + '500': + description: Internal service error + content: + application/json: + schema: + $ref: '#/components/schemas/Error500' + '503': + description: Provider temporarily unavailable + content: + application/json: + schema: + $ref: '#/components/schemas/Error503' + /stablecoins/{stablecoinId}/operations: + parameters: + - name: stablecoinId + in: path + description: System-generated stablecoin identifier + required: true + schema: + type: string + get: + summary: List stablecoin issuer operations + description: List issuer mint and burn operations for a stablecoin, most recent first, with cursor pagination. + operationId: listStablecoinOperations + tags: + - Stablecoins + security: + - BasicAuth: [] + parameters: + - name: limit + in: query + description: Maximum number of results to return (default 20, max 100) + required: false + schema: + type: integer + minimum: 1 + maximum: 100 + default: 20 + - name: cursor + in: query + description: Opaque cursor returned as `nextCursor` from the previous response. + required: false + schema: + type: string + responses: + '200': + description: Successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/StablecoinOperationListResponse' + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/Error401' + '404': + description: Stablecoin not found + content: + application/json: + schema: + $ref: '#/components/schemas/Error404' + '500': + description: Internal service error + content: + application/json: + schema: + $ref: '#/components/schemas/Error500' + /stablecoin-operations/{stablecoinOperationId}: + parameters: + - name: stablecoinOperationId + in: path + description: System-generated stablecoin issuer operation identifier + required: true + schema: + type: string + get: + summary: Get a stablecoin issuer operation + description: Retrieve a single stablecoin issuer operation by its Grid identifier. + operationId: getStablecoinOperation + tags: + - Stablecoins + security: + - BasicAuth: [] + responses: + '200': + description: Successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/StablecoinOperation' + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/Error401' + '404': + description: Stablecoin operation not found + content: + application/json: + schema: + $ref: '#/components/schemas/Error404' + '500': + description: Internal service error + content: + application/json: + schema: + $ref: '#/components/schemas/Error500' /stablecoin-provider-accounts: post: summary: Link a stablecoin provider account @@ -20207,24 +20619,481 @@ components: description: Return amount in the smallest unit of the transaction's currency. Must be less than or equal to the net settled amount (settled minus previously-refunded). exclusiveMinimum: 0 example: 1500 + StablecoinIssuanceStatus: + type: string + enum: + - PENDING_REVIEW + - PROVISIONING + - PROVISIONED + - REJECTED + - FAILED + description: Provider issuance/linking status for the registered stablecoin. + StablecoinGridOperationsStatus: + type: string + enum: + - NOT_ENABLED + - PENDING_APPROVAL + - ENABLING + - ENABLED + - DISABLED + description: Whether the stablecoin has been enabled for normal Grid operations. StablecoinProvider: type: string enum: - BRALE description: Stablecoin provider backing the linked account, stablecoin, or operation. - StablecoinProviderAccountStatus: + StablecoinNetwork: type: string enum: - - ACTIVE - - INVALID - - REVOKED - description: Status of the linked stablecoin provider account credentials. + - SPARK + description: Public network family for the stablecoin token identifier. The concrete Spark network is inferred from the platform mode. StablecoinProviderEnvironment: type: string enum: - SANDBOX - PRODUCTION description: Provider environment derived from the authenticated Grid platform mode. + Stablecoin: + 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: '#/components/schemas/StablecoinNetwork' + decimals: + type: integer + description: Number of decimal places used by the stablecoin. + example: 6 + issuanceStatus: + $ref: '#/components/schemas/StablecoinIssuanceStatus' + gridOperationsStatus: + $ref: '#/components/schemas/StablecoinGridOperationsStatus' + 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: '#/components/schemas/StablecoinProvider' + stablecoinProviderAccountId: + type: string + description: Stablecoin provider account link selected for this stablecoin. + example: StablecoinProviderAccount:019542f5-b3e7-1d02-0000-000000000001 + providerEnvironment: + $ref: '#/components/schemas/StablecoinProviderEnvironment' + 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' + StablecoinListResponse: + type: object + required: + - data + - hasMore + properties: + data: + type: array + items: + $ref: '#/components/schemas/Stablecoin' + 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. + StablecoinRegisterRequest: + type: object + required: + - providerTokenIdentifier + - networkTokenIdentifier + - network + properties: + providerTokenIdentifier: + type: string + description: Provider identifier for the stablecoin. For Brale this maps to `value_type`. + example: ACME + networkTokenIdentifier: + type: string + description: Token identifier in the namespace selected by `network`. + example: btkn1qw508d6qejxtdg4y5r3zarvary0c5xw7k + network: + $ref: '#/components/schemas/StablecoinNetwork' + stablecoinProviderAccountId: + type: string + description: Provider account link to register against. Optional when exactly one active link exists for the authenticated platform; required to resolve STABLECOIN_PROVIDER_ACCOUNT_SELECTION_REQUIRED when multiple links exist. + example: StablecoinProviderAccount:019542f5-b3e7-1d02-0000-000000000001 + StablecoinMintFundingSource: + 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. For `ACH_DEBIT` and `SAME_DAY_ACH_DEBIT`, `externalAccountId` is required. Grid internal account and provider internal balance funding are reserved for follow-up support. + externalAccountId: + type: string + description: Grid `ExternalAccount` used as the ACH debit funding account. + example: ExternalAccount:019542f5-b3e7-1d02-0000-000000000101 + accountId: + type: string + description: Grid internal funding account id for future Grid-funded mint flows. + example: InternalAccount:019542f5-b3e7-1d02-0000-000000000102 + sourceTokenIdentifier: + type: string + description: Provider token/value type for future provider internal balance funding. + example: USDC + cryptoNetwork: + type: string + description: Source crypto network for future provider internal balance funding. + example: SOLANA + StablecoinMintDestination: + type: object + required: + - type + properties: + type: + type: string + enum: + - EXTERNAL_ACCOUNT + - GRID_INTERNAL_ACCOUNT + description: Mint destination variant. In the initial Brale-backed flow, `EXTERNAL_ACCOUNT` must reference an active Spark external account. + externalAccountId: + type: string + description: Grid `ExternalAccount` receiving the minted stablecoin. + example: ExternalAccount:019542f5-b3e7-1d02-0000-000000000201 + accountId: + type: string + description: Grid internal receiving account id for future Grid-managed mint destinations. + example: InternalAccount:019542f5-b3e7-1d02-0000-000000000202 + StablecoinMintRequest: + type: object + required: + - amount + - fundingSource + - destination + properties: + amount: + type: string + pattern: ^[0-9]+$ + description: Amount to mint in the stablecoin's smallest unit. The amount must convert exactly to a whole fiat cent for the token decimals. + example: '1000000' + fundingSource: + $ref: '#/components/schemas/StablecoinMintFundingSource' + destination: + $ref: '#/components/schemas/StablecoinMintDestination' + description: + type: string + maxLength: 1024 + description: Optional platform-provided operation description. + example: Initial program funding mint + StablecoinOperationType: + type: string + enum: + - MINT + - BURN + description: Stablecoin issuer operation type. + StablecoinOperationStatus: + type: string + enum: + - CREATED + - PENDING_FUNDING + - PENDING_PROVIDER + - PROCESSING + - COMPLETED + - FAILED + - EXPIRED + description: Stablecoin issuer operation lifecycle status. + StablecoinBurnSource: + type: object + required: + - type + properties: + type: + type: string + enum: + - EXTERNAL_ACCOUNT + - GRID_INTERNAL_ACCOUNT + - PROVIDER_INTERNAL_BALANCE + description: Burn source variant. `EXTERNAL_ACCOUNT` references an active Spark external account and returns funding instructions. `PROVIDER_INTERNAL_BALANCE` spends stablecoin funds already at the provider. Grid internal account burns are reserved for the Grid-enabled ledger movement flow. + externalAccountId: + type: string + description: Grid Spark `ExternalAccount` expected to fund the provider for external-source burns. + example: ExternalAccount:019542f5-b3e7-1d02-0000-000000000203 + accountId: + type: string + description: Grid internal source account id for future Grid-controlled burn flows. + example: InternalAccount:019542f5-b3e7-1d02-0000-000000000204 + StablecoinFundingInstructions: + type: object + description: Provider funding instructions safe to show publicly. Present for wire-funded mint operations and external-source burn operations when available. + additionalProperties: true + example: + rail: SPARK + network: SPARK + address: spark1... + valueType: ACME + StablecoinOperationDestination: + type: object + description: 'Destination of a stablecoin operation, as reported on a `StablecoinOperation`. A single merged shape (superset of the mint and burn destination request variants) so the field is unambiguously deserializable regardless of operation type: `rail` is present for burn (fiat payout) destinations and absent for mint destinations.' + required: + - type + properties: + type: + type: string + enum: + - EXTERNAL_ACCOUNT + - GRID_INTERNAL_ACCOUNT + description: Destination variant. + externalAccountId: + type: string + description: Grid `ExternalAccount` id, when the destination is an external account. + example: ExternalAccount:019542f5-b3e7-1d02-0000-000000000205 + accountId: + type: string + description: Grid internal account id, when the destination is a Grid-managed account. + example: InternalAccount:019542f5-b3e7-1d02-0000-000000000202 + rail: + type: string + enum: + - WIRE + - ACH_CREDIT + - SAME_DAY_ACH_CREDIT + - RTP_CREDIT + description: Fiat payout rail, present for burn (fiat redemption) destinations. + StablecoinEstimatedDelivery: + type: object + description: Static rail timing estimate for fiat redemption delivery. This is guidance, not a guaranteed arrival time. + additionalProperties: true + example: + rail: ACH_CREDIT + amount: '1.00' + currency: USD + timing: 1-3 business days + StablecoinOperation: + type: object + required: + - id + - stablecoinId + - operationType + - status + - amount + - provider + - providerEnvironment + - stablecoinProviderAccountId + - createdAt + - updatedAt + properties: + id: + type: string + description: System-generated stablecoin issuer operation identifier. + example: StablecoinOperation:019542f5-b3e7-1d02-0000-000000000301 + stablecoinId: + type: string + description: Stablecoin this operation belongs to. + example: Stablecoin:019542f5-b3e7-1d02-0000-000000000002 + operationType: + $ref: '#/components/schemas/StablecoinOperationType' + status: + $ref: '#/components/schemas/StablecoinOperationStatus' + amount: + type: string + description: Operation amount in the stablecoin's smallest unit. + example: '1000000' + provider: + $ref: '#/components/schemas/StablecoinProvider' + providerEnvironment: + $ref: '#/components/schemas/StablecoinProviderEnvironment' + stablecoinProviderAccountId: + type: string + description: Stablecoin provider account link used for the operation. + example: StablecoinProviderAccount:019542f5-b3e7-1d02-0000-000000000001 + fundingSource: + $ref: '#/components/schemas/StablecoinMintFundingSource' + source: + $ref: '#/components/schemas/StablecoinBurnSource' + fundingInstructions: + $ref: '#/components/schemas/StablecoinFundingInstructions' + destination: + $ref: '#/components/schemas/StablecoinOperationDestination' + estimatedDelivery: + $ref: '#/components/schemas/StablecoinEstimatedDelivery' + expiresAt: + type: string + format: date-time + description: Expiry for operations awaiting external funding. + example: '2026-05-27T16:40:00Z' + providerStatus: + type: string + description: Sanitized provider status when available. + example: pending + failureReason: + type: string + description: Stable internal failure code for terminal failed operations. + example: PROVIDER_TRANSFER_FAILED + description: + type: string + description: Platform-provided operation description. + example: Initial program funding mint + 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' + Error503: + 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 + StablecoinBurnDestination: + 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. + StablecoinBurnRequest: + 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: '#/components/schemas/StablecoinBurnSource' + destination: + $ref: '#/components/schemas/StablecoinBurnDestination' + description: + type: string + maxLength: 1024 + description: Optional platform-provided operation description. + example: Redeem ACME + StablecoinOperationListResponse: + type: object + required: + - data + - hasMore + properties: + data: + type: array + items: + $ref: '#/components/schemas/StablecoinOperation' + 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 stablecoin operations matching the query. + StablecoinProviderAccountStatus: + type: string + enum: + - ACTIVE + - INVALID + - REVOKED + description: Status of the linked stablecoin provider account credentials. StablecoinProviderAccount: type: object required: diff --git a/openapi.yaml b/openapi.yaml index 476be1e8d..9671b1c24 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -58,7 +58,7 @@ tags: - name: Cards description: Card management endpoints. Issue debit cards against an internal account, freeze / unfreeze, close, manage card funding sources, and list card transactions. - name: Stablecoins - description: Stablecoin issuance endpoints. Link provider accounts, register provider-created stablecoins, create mint/burn quotes, execute them, and track the resulting operations. + description: Stablecoin issuance endpoints. Link provider accounts, register provider-created stablecoins, create direct mint/burn issuer operations, and track operation status. paths: /config: get: @@ -7481,6 +7481,418 @@ paths: application/json: schema: $ref: '#/components/schemas/Error500' + /stablecoins: + post: + summary: Register an existing provider-created stablecoin + description: | + Register an existing provider-created stablecoin as a Grid `Stablecoin`. This endpoint links provider token metadata to Grid; it does not create the token with the provider. Grid derives the active provider account link from the authenticated platform, provider, and provider environment. + operationId: registerStablecoin + tags: + - Stablecoins + security: + - BasicAuth: [] + parameters: + - name: Idempotency-Key + in: header + description: Required idempotency key for retrying this request safely. + required: true + schema: + type: string + maxLength: 255 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/StablecoinRegisterRequest' + responses: + '201': + description: Stablecoin registered + content: + application/json: + schema: + $ref: '#/components/schemas/Stablecoin' + '400': + description: Bad request + content: + application/json: + schema: + $ref: '#/components/schemas/Error400' + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/Error401' + '404': + description: Referenced stablecoin provider account not found + content: + application/json: + schema: + $ref: '#/components/schemas/Error404' + '409': + description: Conflict + content: + application/json: + schema: + $ref: '#/components/schemas/Error409' + '500': + description: Internal service error + content: + application/json: + schema: + $ref: '#/components/schemas/Error500' + get: + summary: List stablecoins + description: Retrieve stablecoins registered to the authenticated platform. + operationId: listStablecoins + tags: + - Stablecoins + security: + - BasicAuth: [] + parameters: + - name: issuanceStatus + in: query + required: false + schema: + $ref: '#/components/schemas/StablecoinIssuanceStatus' + - name: gridOperationsStatus + in: query + required: false + schema: + $ref: '#/components/schemas/StablecoinGridOperationsStatus' + - name: provider + in: query + required: false + schema: + $ref: '#/components/schemas/StablecoinProvider' + - name: limit + in: query + description: Maximum number of results to return (default 20, max 100) + required: false + schema: + type: integer + minimum: 1 + maximum: 100 + default: 20 + - name: cursor + in: query + description: Opaque cursor returned as `nextCursor` from the previous response. + required: false + schema: + type: string + responses: + '200': + description: Successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/StablecoinListResponse' + '400': + description: Bad request - Invalid parameters + content: + application/json: + schema: + $ref: '#/components/schemas/Error400' + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/Error401' + '500': + description: Internal service error + content: + application/json: + schema: + $ref: '#/components/schemas/Error500' + /stablecoins/{stablecoinId}: + parameters: + - name: stablecoinId + in: path + description: System-generated stablecoin identifier + required: true + schema: + type: string + get: + summary: Get a stablecoin + description: Retrieve a single registered stablecoin by its Grid identifier. + operationId: getStablecoin + tags: + - Stablecoins + security: + - BasicAuth: [] + responses: + '200': + description: Successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/Stablecoin' + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/Error401' + '404': + description: Stablecoin not found + content: + application/json: + schema: + $ref: '#/components/schemas/Error404' + '500': + description: Internal service error + content: + application/json: + schema: + $ref: '#/components/schemas/Error500' + /stablecoins/{stablecoinId}/mints: + parameters: + - name: stablecoinId + in: path + description: System-generated stablecoin identifier + required: true + schema: + type: string + post: + summary: Create a stablecoin mint operation + description: | + Create a provider-backed mint operation for a registered stablecoin. Funding and destination accounts are normal Grid `ExternalAccount` objects; any provider-specific Brale address linkage is managed internally by Grid. Wire-funded mints return funding instructions and remain pending until the provider reports funds received. + operationId: createStablecoinMint + tags: + - Stablecoins + security: + - BasicAuth: [] + parameters: + - name: Idempotency-Key + in: header + description: Required idempotency key for retrying this mint request safely. + required: true + schema: + type: string + maxLength: 255 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/StablecoinMintRequest' + responses: + '201': + description: Mint operation created + content: + application/json: + schema: + $ref: '#/components/schemas/StablecoinOperation' + '400': + description: Bad request + content: + application/json: + schema: + $ref: '#/components/schemas/Error400' + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/Error401' + '404': + description: Stablecoin or referenced account not found + content: + application/json: + schema: + $ref: '#/components/schemas/Error404' + '409': + description: Conflict + content: + application/json: + schema: + $ref: '#/components/schemas/Error409' + '500': + description: Internal service error + content: + application/json: + schema: + $ref: '#/components/schemas/Error500' + '503': + description: Provider temporarily unavailable + content: + application/json: + schema: + $ref: '#/components/schemas/Error503' + /stablecoins/{stablecoinId}/burns: + parameters: + - name: stablecoinId + in: path + description: System-generated stablecoin identifier + required: true + schema: + type: string + post: + summary: Create a stablecoin burn operation + description: | + Create a provider-backed burn/redemption operation for a registered stablecoin. Burn sources and fiat destinations are normal Grid account objects; provider-specific Brale address ids are resolved and stored internally. External Spark wallet sources return funding instructions and remain pending until the provider reports funds received. + operationId: createStablecoinBurn + tags: + - Stablecoins + security: + - BasicAuth: [] + parameters: + - name: Idempotency-Key + in: header + description: Required idempotency key for retrying this burn request safely. + required: true + schema: + type: string + maxLength: 255 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/StablecoinBurnRequest' + responses: + '201': + description: Burn operation created + content: + application/json: + schema: + $ref: '#/components/schemas/StablecoinOperation' + '400': + description: Bad request + content: + application/json: + schema: + $ref: '#/components/schemas/Error400' + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/Error401' + '404': + description: Stablecoin or referenced account not found + content: + application/json: + schema: + $ref: '#/components/schemas/Error404' + '409': + description: Conflict + content: + application/json: + schema: + $ref: '#/components/schemas/Error409' + '500': + description: Internal service error + content: + application/json: + schema: + $ref: '#/components/schemas/Error500' + '503': + description: Provider temporarily unavailable + content: + application/json: + schema: + $ref: '#/components/schemas/Error503' + /stablecoins/{stablecoinId}/operations: + parameters: + - name: stablecoinId + in: path + description: System-generated stablecoin identifier + required: true + schema: + type: string + get: + summary: List stablecoin issuer operations + description: List issuer mint and burn operations for a stablecoin, most recent first, with cursor pagination. + operationId: listStablecoinOperations + tags: + - Stablecoins + security: + - BasicAuth: [] + parameters: + - name: limit + in: query + description: Maximum number of results to return (default 20, max 100) + required: false + schema: + type: integer + minimum: 1 + maximum: 100 + default: 20 + - name: cursor + in: query + description: Opaque cursor returned as `nextCursor` from the previous response. + required: false + schema: + type: string + responses: + '200': + description: Successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/StablecoinOperationListResponse' + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/Error401' + '404': + description: Stablecoin not found + content: + application/json: + schema: + $ref: '#/components/schemas/Error404' + '500': + description: Internal service error + content: + application/json: + schema: + $ref: '#/components/schemas/Error500' + /stablecoin-operations/{stablecoinOperationId}: + parameters: + - name: stablecoinOperationId + in: path + description: System-generated stablecoin issuer operation identifier + required: true + schema: + type: string + get: + summary: Get a stablecoin issuer operation + description: Retrieve a single stablecoin issuer operation by its Grid identifier. + operationId: getStablecoinOperation + tags: + - Stablecoins + security: + - BasicAuth: [] + responses: + '200': + description: Successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/StablecoinOperation' + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/Error401' + '404': + description: Stablecoin operation not found + content: + application/json: + schema: + $ref: '#/components/schemas/Error404' + '500': + description: Internal service error + content: + application/json: + schema: + $ref: '#/components/schemas/Error500' /stablecoin-provider-accounts: post: summary: Link a stablecoin provider account @@ -20207,24 +20619,481 @@ components: description: Return amount in the smallest unit of the transaction's currency. Must be less than or equal to the net settled amount (settled minus previously-refunded). exclusiveMinimum: 0 example: 1500 + StablecoinIssuanceStatus: + type: string + enum: + - PENDING_REVIEW + - PROVISIONING + - PROVISIONED + - REJECTED + - FAILED + description: Provider issuance/linking status for the registered stablecoin. + StablecoinGridOperationsStatus: + type: string + enum: + - NOT_ENABLED + - PENDING_APPROVAL + - ENABLING + - ENABLED + - DISABLED + description: Whether the stablecoin has been enabled for normal Grid operations. StablecoinProvider: type: string enum: - BRALE description: Stablecoin provider backing the linked account, stablecoin, or operation. - StablecoinProviderAccountStatus: + StablecoinNetwork: type: string enum: - - ACTIVE - - INVALID - - REVOKED - description: Status of the linked stablecoin provider account credentials. + - SPARK + description: Public network family for the stablecoin token identifier. The concrete Spark network is inferred from the platform mode. StablecoinProviderEnvironment: type: string enum: - SANDBOX - PRODUCTION description: Provider environment derived from the authenticated Grid platform mode. + Stablecoin: + 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: '#/components/schemas/StablecoinNetwork' + decimals: + type: integer + description: Number of decimal places used by the stablecoin. + example: 6 + issuanceStatus: + $ref: '#/components/schemas/StablecoinIssuanceStatus' + gridOperationsStatus: + $ref: '#/components/schemas/StablecoinGridOperationsStatus' + 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: '#/components/schemas/StablecoinProvider' + stablecoinProviderAccountId: + type: string + description: Stablecoin provider account link selected for this stablecoin. + example: StablecoinProviderAccount:019542f5-b3e7-1d02-0000-000000000001 + providerEnvironment: + $ref: '#/components/schemas/StablecoinProviderEnvironment' + 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' + StablecoinListResponse: + type: object + required: + - data + - hasMore + properties: + data: + type: array + items: + $ref: '#/components/schemas/Stablecoin' + 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. + StablecoinRegisterRequest: + type: object + required: + - providerTokenIdentifier + - networkTokenIdentifier + - network + properties: + providerTokenIdentifier: + type: string + description: Provider identifier for the stablecoin. For Brale this maps to `value_type`. + example: ACME + networkTokenIdentifier: + type: string + description: Token identifier in the namespace selected by `network`. + example: btkn1qw508d6qejxtdg4y5r3zarvary0c5xw7k + network: + $ref: '#/components/schemas/StablecoinNetwork' + stablecoinProviderAccountId: + type: string + description: Provider account link to register against. Optional when exactly one active link exists for the authenticated platform; required to resolve STABLECOIN_PROVIDER_ACCOUNT_SELECTION_REQUIRED when multiple links exist. + example: StablecoinProviderAccount:019542f5-b3e7-1d02-0000-000000000001 + StablecoinMintFundingSource: + 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. For `ACH_DEBIT` and `SAME_DAY_ACH_DEBIT`, `externalAccountId` is required. Grid internal account and provider internal balance funding are reserved for follow-up support. + externalAccountId: + type: string + description: Grid `ExternalAccount` used as the ACH debit funding account. + example: ExternalAccount:019542f5-b3e7-1d02-0000-000000000101 + accountId: + type: string + description: Grid internal funding account id for future Grid-funded mint flows. + example: InternalAccount:019542f5-b3e7-1d02-0000-000000000102 + sourceTokenIdentifier: + type: string + description: Provider token/value type for future provider internal balance funding. + example: USDC + cryptoNetwork: + type: string + description: Source crypto network for future provider internal balance funding. + example: SOLANA + StablecoinMintDestination: + type: object + required: + - type + properties: + type: + type: string + enum: + - EXTERNAL_ACCOUNT + - GRID_INTERNAL_ACCOUNT + description: Mint destination variant. In the initial Brale-backed flow, `EXTERNAL_ACCOUNT` must reference an active Spark external account. + externalAccountId: + type: string + description: Grid `ExternalAccount` receiving the minted stablecoin. + example: ExternalAccount:019542f5-b3e7-1d02-0000-000000000201 + accountId: + type: string + description: Grid internal receiving account id for future Grid-managed mint destinations. + example: InternalAccount:019542f5-b3e7-1d02-0000-000000000202 + StablecoinMintRequest: + type: object + required: + - amount + - fundingSource + - destination + properties: + amount: + type: string + pattern: ^[0-9]+$ + description: Amount to mint in the stablecoin's smallest unit. The amount must convert exactly to a whole fiat cent for the token decimals. + example: '1000000' + fundingSource: + $ref: '#/components/schemas/StablecoinMintFundingSource' + destination: + $ref: '#/components/schemas/StablecoinMintDestination' + description: + type: string + maxLength: 1024 + description: Optional platform-provided operation description. + example: Initial program funding mint + StablecoinOperationType: + type: string + enum: + - MINT + - BURN + description: Stablecoin issuer operation type. + StablecoinOperationStatus: + type: string + enum: + - CREATED + - PENDING_FUNDING + - PENDING_PROVIDER + - PROCESSING + - COMPLETED + - FAILED + - EXPIRED + description: Stablecoin issuer operation lifecycle status. + StablecoinBurnSource: + type: object + required: + - type + properties: + type: + type: string + enum: + - EXTERNAL_ACCOUNT + - GRID_INTERNAL_ACCOUNT + - PROVIDER_INTERNAL_BALANCE + description: Burn source variant. `EXTERNAL_ACCOUNT` references an active Spark external account and returns funding instructions. `PROVIDER_INTERNAL_BALANCE` spends stablecoin funds already at the provider. Grid internal account burns are reserved for the Grid-enabled ledger movement flow. + externalAccountId: + type: string + description: Grid Spark `ExternalAccount` expected to fund the provider for external-source burns. + example: ExternalAccount:019542f5-b3e7-1d02-0000-000000000203 + accountId: + type: string + description: Grid internal source account id for future Grid-controlled burn flows. + example: InternalAccount:019542f5-b3e7-1d02-0000-000000000204 + StablecoinFundingInstructions: + type: object + description: Provider funding instructions safe to show publicly. Present for wire-funded mint operations and external-source burn operations when available. + additionalProperties: true + example: + rail: SPARK + network: SPARK + address: spark1... + valueType: ACME + StablecoinOperationDestination: + type: object + description: 'Destination of a stablecoin operation, as reported on a `StablecoinOperation`. A single merged shape (superset of the mint and burn destination request variants) so the field is unambiguously deserializable regardless of operation type: `rail` is present for burn (fiat payout) destinations and absent for mint destinations.' + required: + - type + properties: + type: + type: string + enum: + - EXTERNAL_ACCOUNT + - GRID_INTERNAL_ACCOUNT + description: Destination variant. + externalAccountId: + type: string + description: Grid `ExternalAccount` id, when the destination is an external account. + example: ExternalAccount:019542f5-b3e7-1d02-0000-000000000205 + accountId: + type: string + description: Grid internal account id, when the destination is a Grid-managed account. + example: InternalAccount:019542f5-b3e7-1d02-0000-000000000202 + rail: + type: string + enum: + - WIRE + - ACH_CREDIT + - SAME_DAY_ACH_CREDIT + - RTP_CREDIT + description: Fiat payout rail, present for burn (fiat redemption) destinations. + StablecoinEstimatedDelivery: + type: object + description: Static rail timing estimate for fiat redemption delivery. This is guidance, not a guaranteed arrival time. + additionalProperties: true + example: + rail: ACH_CREDIT + amount: '1.00' + currency: USD + timing: 1-3 business days + StablecoinOperation: + type: object + required: + - id + - stablecoinId + - operationType + - status + - amount + - provider + - providerEnvironment + - stablecoinProviderAccountId + - createdAt + - updatedAt + properties: + id: + type: string + description: System-generated stablecoin issuer operation identifier. + example: StablecoinOperation:019542f5-b3e7-1d02-0000-000000000301 + stablecoinId: + type: string + description: Stablecoin this operation belongs to. + example: Stablecoin:019542f5-b3e7-1d02-0000-000000000002 + operationType: + $ref: '#/components/schemas/StablecoinOperationType' + status: + $ref: '#/components/schemas/StablecoinOperationStatus' + amount: + type: string + description: Operation amount in the stablecoin's smallest unit. + example: '1000000' + provider: + $ref: '#/components/schemas/StablecoinProvider' + providerEnvironment: + $ref: '#/components/schemas/StablecoinProviderEnvironment' + stablecoinProviderAccountId: + type: string + description: Stablecoin provider account link used for the operation. + example: StablecoinProviderAccount:019542f5-b3e7-1d02-0000-000000000001 + fundingSource: + $ref: '#/components/schemas/StablecoinMintFundingSource' + source: + $ref: '#/components/schemas/StablecoinBurnSource' + fundingInstructions: + $ref: '#/components/schemas/StablecoinFundingInstructions' + destination: + $ref: '#/components/schemas/StablecoinOperationDestination' + estimatedDelivery: + $ref: '#/components/schemas/StablecoinEstimatedDelivery' + expiresAt: + type: string + format: date-time + description: Expiry for operations awaiting external funding. + example: '2026-05-27T16:40:00Z' + providerStatus: + type: string + description: Sanitized provider status when available. + example: pending + failureReason: + type: string + description: Stable internal failure code for terminal failed operations. + example: PROVIDER_TRANSFER_FAILED + description: + type: string + description: Platform-provided operation description. + example: Initial program funding mint + 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' + Error503: + 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 + StablecoinBurnDestination: + 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. + StablecoinBurnRequest: + 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: '#/components/schemas/StablecoinBurnSource' + destination: + $ref: '#/components/schemas/StablecoinBurnDestination' + description: + type: string + maxLength: 1024 + description: Optional platform-provided operation description. + example: Redeem ACME + StablecoinOperationListResponse: + type: object + required: + - data + - hasMore + properties: + data: + type: array + items: + $ref: '#/components/schemas/StablecoinOperation' + 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 stablecoin operations matching the query. + StablecoinProviderAccountStatus: + type: string + enum: + - ACTIVE + - INVALID + - REVOKED + description: Status of the linked stablecoin provider account credentials. StablecoinProviderAccount: type: object required: diff --git a/openapi/components/schemas/errors/Error503.yaml b/openapi/components/schemas/errors/Error503.yaml new file mode 100644 index 000000000..dd695d51b --- /dev/null +++ b/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 diff --git a/openapi/components/schemas/stablecoins/Stablecoin.yaml b/openapi/components/schemas/stablecoins/Stablecoin.yaml new file mode 100644 index 000000000..c8584d881 --- /dev/null +++ b/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' diff --git a/openapi/components/schemas/stablecoins/StablecoinBurnDestination.yaml b/openapi/components/schemas/stablecoins/StablecoinBurnDestination.yaml new file mode 100644 index 000000000..9fe648759 --- /dev/null +++ b/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. diff --git a/openapi/components/schemas/stablecoins/StablecoinBurnRequest.yaml b/openapi/components/schemas/stablecoins/StablecoinBurnRequest.yaml new file mode 100644 index 000000000..1071ad735 --- /dev/null +++ b/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 diff --git a/openapi/components/schemas/stablecoins/StablecoinBurnSource.yaml b/openapi/components/schemas/stablecoins/StablecoinBurnSource.yaml new file mode 100644 index 000000000..13d766e62 --- /dev/null +++ b/openapi/components/schemas/stablecoins/StablecoinBurnSource.yaml @@ -0,0 +1,19 @@ +type: object +required: + - type +properties: + type: + type: string + enum: + - EXTERNAL_ACCOUNT + - GRID_INTERNAL_ACCOUNT + - PROVIDER_INTERNAL_BALANCE + description: Burn source variant. `EXTERNAL_ACCOUNT` references an active Spark external account and returns funding instructions. `PROVIDER_INTERNAL_BALANCE` spends stablecoin funds already at the provider. Grid internal account burns are reserved for the Grid-enabled ledger movement flow. + externalAccountId: + type: string + description: Grid Spark `ExternalAccount` expected to fund the provider for external-source burns. + example: ExternalAccount:019542f5-b3e7-1d02-0000-000000000203 + accountId: + type: string + description: Grid internal source account id for future Grid-controlled burn flows. + example: InternalAccount:019542f5-b3e7-1d02-0000-000000000204 diff --git a/openapi/components/schemas/stablecoins/StablecoinEstimatedDelivery.yaml b/openapi/components/schemas/stablecoins/StablecoinEstimatedDelivery.yaml new file mode 100644 index 000000000..eeb292e71 --- /dev/null +++ b/openapi/components/schemas/stablecoins/StablecoinEstimatedDelivery.yaml @@ -0,0 +1,8 @@ +type: object +description: Static rail timing estimate for fiat redemption delivery. This is guidance, not a guaranteed arrival time. +additionalProperties: true +example: + rail: ACH_CREDIT + amount: '1.00' + currency: USD + timing: 1-3 business days diff --git a/openapi/components/schemas/stablecoins/StablecoinFundingInstructions.yaml b/openapi/components/schemas/stablecoins/StablecoinFundingInstructions.yaml new file mode 100644 index 000000000..d9184dc0d --- /dev/null +++ b/openapi/components/schemas/stablecoins/StablecoinFundingInstructions.yaml @@ -0,0 +1,8 @@ +type: object +description: Provider funding instructions safe to show publicly. Present for wire-funded mint operations and external-source burn operations when available. +additionalProperties: true +example: + rail: SPARK + network: SPARK + address: spark1... + valueType: ACME diff --git a/openapi/components/schemas/stablecoins/StablecoinGridOperationsStatus.yaml b/openapi/components/schemas/stablecoins/StablecoinGridOperationsStatus.yaml new file mode 100644 index 000000000..3c8ac4989 --- /dev/null +++ b/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. diff --git a/openapi/components/schemas/stablecoins/StablecoinIssuanceStatus.yaml b/openapi/components/schemas/stablecoins/StablecoinIssuanceStatus.yaml new file mode 100644 index 000000000..fa65ab5b2 --- /dev/null +++ b/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. diff --git a/openapi/components/schemas/stablecoins/StablecoinListResponse.yaml b/openapi/components/schemas/stablecoins/StablecoinListResponse.yaml new file mode 100644 index 000000000..c1ebd7b2e --- /dev/null +++ b/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. diff --git a/openapi/components/schemas/stablecoins/StablecoinMintDestination.yaml b/openapi/components/schemas/stablecoins/StablecoinMintDestination.yaml new file mode 100644 index 000000000..60f50a568 --- /dev/null +++ b/openapi/components/schemas/stablecoins/StablecoinMintDestination.yaml @@ -0,0 +1,18 @@ +type: object +required: + - type +properties: + type: + type: string + enum: + - EXTERNAL_ACCOUNT + - GRID_INTERNAL_ACCOUNT + description: Mint destination variant. In the initial Brale-backed flow, `EXTERNAL_ACCOUNT` must reference an active Spark external account. + externalAccountId: + type: string + description: Grid `ExternalAccount` receiving the minted stablecoin. + example: ExternalAccount:019542f5-b3e7-1d02-0000-000000000201 + accountId: + type: string + description: Grid internal receiving account id for future Grid-managed mint destinations. + example: InternalAccount:019542f5-b3e7-1d02-0000-000000000202 diff --git a/openapi/components/schemas/stablecoins/StablecoinMintFundingSource.yaml b/openapi/components/schemas/stablecoins/StablecoinMintFundingSource.yaml new file mode 100644 index 000000000..ce0d30684 --- /dev/null +++ b/openapi/components/schemas/stablecoins/StablecoinMintFundingSource.yaml @@ -0,0 +1,29 @@ +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. For `ACH_DEBIT` and `SAME_DAY_ACH_DEBIT`, `externalAccountId` is required. Grid internal account and provider internal balance funding are reserved for follow-up support. + externalAccountId: + type: string + description: Grid `ExternalAccount` used as the ACH debit funding account. + example: ExternalAccount:019542f5-b3e7-1d02-0000-000000000101 + accountId: + type: string + description: Grid internal funding account id for future Grid-funded mint flows. + example: InternalAccount:019542f5-b3e7-1d02-0000-000000000102 + sourceTokenIdentifier: + type: string + description: Provider token/value type for future provider internal balance funding. + example: USDC + cryptoNetwork: + type: string + description: Source crypto network for future provider internal balance funding. + example: SOLANA diff --git a/openapi/components/schemas/stablecoins/StablecoinMintRequest.yaml b/openapi/components/schemas/stablecoins/StablecoinMintRequest.yaml new file mode 100644 index 000000000..7979864f0 --- /dev/null +++ b/openapi/components/schemas/stablecoins/StablecoinMintRequest.yaml @@ -0,0 +1,20 @@ +type: object +required: + - amount + - fundingSource + - destination +properties: + amount: + type: string + pattern: '^[0-9]+$' + description: Amount to mint in the stablecoin's smallest unit. The amount must convert exactly to a whole fiat cent for the token decimals. + example: '1000000' + fundingSource: + $ref: StablecoinMintFundingSource.yaml + destination: + $ref: StablecoinMintDestination.yaml + description: + type: string + maxLength: 1024 + description: Optional platform-provided operation description. + example: Initial program funding mint diff --git a/openapi/components/schemas/stablecoins/StablecoinNetwork.yaml b/openapi/components/schemas/stablecoins/StablecoinNetwork.yaml new file mode 100644 index 000000000..1f1e01760 --- /dev/null +++ b/openapi/components/schemas/stablecoins/StablecoinNetwork.yaml @@ -0,0 +1,4 @@ +type: string +enum: + - SPARK +description: Public network family for the stablecoin token identifier. The concrete Spark network is inferred from the platform mode. diff --git a/openapi/components/schemas/stablecoins/StablecoinOperation.yaml b/openapi/components/schemas/stablecoins/StablecoinOperation.yaml new file mode 100644 index 000000000..1a0c28f5f --- /dev/null +++ b/openapi/components/schemas/stablecoins/StablecoinOperation.yaml @@ -0,0 +1,74 @@ +type: object +required: + - id + - stablecoinId + - operationType + - status + - amount + - provider + - providerEnvironment + - stablecoinProviderAccountId + - createdAt + - updatedAt +properties: + id: + type: string + description: System-generated stablecoin issuer operation identifier. + example: StablecoinOperation:019542f5-b3e7-1d02-0000-000000000301 + stablecoinId: + type: string + description: Stablecoin this operation belongs to. + example: Stablecoin:019542f5-b3e7-1d02-0000-000000000002 + operationType: + $ref: StablecoinOperationType.yaml + status: + $ref: StablecoinOperationStatus.yaml + amount: + type: string + description: Operation amount in the stablecoin's smallest unit. + example: '1000000' + provider: + $ref: StablecoinProvider.yaml + providerEnvironment: + $ref: StablecoinProviderEnvironment.yaml + stablecoinProviderAccountId: + type: string + description: Stablecoin provider account link used for the operation. + example: StablecoinProviderAccount:019542f5-b3e7-1d02-0000-000000000001 + fundingSource: + $ref: StablecoinMintFundingSource.yaml + source: + $ref: StablecoinBurnSource.yaml + fundingInstructions: + $ref: StablecoinFundingInstructions.yaml + destination: + $ref: StablecoinOperationDestination.yaml + estimatedDelivery: + $ref: StablecoinEstimatedDelivery.yaml + expiresAt: + type: string + format: date-time + description: Expiry for operations awaiting external funding. + example: '2026-05-27T16:40:00Z' + providerStatus: + type: string + description: Sanitized provider status when available. + example: pending + failureReason: + type: string + description: Stable internal failure code for terminal failed operations. + example: PROVIDER_TRANSFER_FAILED + description: + type: string + description: Platform-provided operation description. + example: Initial program funding mint + 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' diff --git a/openapi/components/schemas/stablecoins/StablecoinOperationDestination.yaml b/openapi/components/schemas/stablecoins/StablecoinOperationDestination.yaml new file mode 100644 index 000000000..908bc02ec --- /dev/null +++ b/openapi/components/schemas/stablecoins/StablecoinOperationDestination.yaml @@ -0,0 +1,33 @@ +type: object +description: >- + Destination of a stablecoin operation, as reported on a + `StablecoinOperation`. A single merged shape (superset of the + mint and burn destination request variants) so the field is + unambiguously deserializable regardless of operation type: `rail` + is present for burn (fiat payout) destinations and absent for mint + destinations. +required: + - type +properties: + type: + type: string + enum: + - EXTERNAL_ACCOUNT + - GRID_INTERNAL_ACCOUNT + description: Destination variant. + externalAccountId: + type: string + description: Grid `ExternalAccount` id, when the destination is an external account. + example: ExternalAccount:019542f5-b3e7-1d02-0000-000000000205 + accountId: + type: string + description: Grid internal account id, when the destination is a Grid-managed account. + example: InternalAccount:019542f5-b3e7-1d02-0000-000000000202 + rail: + type: string + enum: + - WIRE + - ACH_CREDIT + - SAME_DAY_ACH_CREDIT + - RTP_CREDIT + description: Fiat payout rail, present for burn (fiat redemption) destinations. diff --git a/openapi/components/schemas/stablecoins/StablecoinOperationListResponse.yaml b/openapi/components/schemas/stablecoins/StablecoinOperationListResponse.yaml new file mode 100644 index 000000000..5a8277bdd --- /dev/null +++ b/openapi/components/schemas/stablecoins/StablecoinOperationListResponse.yaml @@ -0,0 +1,18 @@ +type: object +required: + - data + - hasMore +properties: + data: + type: array + items: + $ref: StablecoinOperation.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 stablecoin operations matching the query. diff --git a/openapi/components/schemas/stablecoins/StablecoinOperationStatus.yaml b/openapi/components/schemas/stablecoins/StablecoinOperationStatus.yaml new file mode 100644 index 000000000..e4b2e803a --- /dev/null +++ b/openapi/components/schemas/stablecoins/StablecoinOperationStatus.yaml @@ -0,0 +1,10 @@ +type: string +enum: + - CREATED + - PENDING_FUNDING + - PENDING_PROVIDER + - PROCESSING + - COMPLETED + - FAILED + - EXPIRED +description: Stablecoin issuer operation lifecycle status. diff --git a/openapi/components/schemas/stablecoins/StablecoinOperationType.yaml b/openapi/components/schemas/stablecoins/StablecoinOperationType.yaml new file mode 100644 index 000000000..e8f0072ee --- /dev/null +++ b/openapi/components/schemas/stablecoins/StablecoinOperationType.yaml @@ -0,0 +1,5 @@ +type: string +enum: + - MINT + - BURN +description: Stablecoin issuer operation type. diff --git a/openapi/components/schemas/stablecoins/StablecoinRegisterRequest.yaml b/openapi/components/schemas/stablecoins/StablecoinRegisterRequest.yaml new file mode 100644 index 000000000..fc2b4e62b --- /dev/null +++ b/openapi/components/schemas/stablecoins/StablecoinRegisterRequest.yaml @@ -0,0 +1,20 @@ +type: object +required: + - providerTokenIdentifier + - networkTokenIdentifier + - network +properties: + providerTokenIdentifier: + type: string + description: Provider identifier for the stablecoin. For Brale this maps to `value_type`. + example: ACME + networkTokenIdentifier: + type: string + description: Token identifier in the namespace selected by `network`. + example: btkn1qw508d6qejxtdg4y5r3zarvary0c5xw7k + network: + $ref: StablecoinNetwork.yaml + stablecoinProviderAccountId: + type: string + description: Provider account link to register against. Optional when exactly one active link exists for the authenticated platform; required to resolve STABLECOIN_PROVIDER_ACCOUNT_SELECTION_REQUIRED when multiple links exist. + example: StablecoinProviderAccount:019542f5-b3e7-1d02-0000-000000000001 diff --git a/openapi/openapi.yaml b/openapi/openapi.yaml index 39ada2584..a56ed33d4 100644 --- a/openapi/openapi.yaml +++ b/openapi/openapi.yaml @@ -85,8 +85,8 @@ tags: - name: Stablecoins description: >- Stablecoin issuance endpoints. Link provider accounts, register - provider-created stablecoins, create mint/burn quotes, execute them, and - track the resulting operations. + provider-created stablecoins, create direct mint/burn issuer operations, + and track operation status. servers: - url: https://api.lightspark.com/grid/2025-10-13 description: Production server @@ -304,6 +304,18 @@ paths: $ref: paths/sandbox/cards/sandbox_cards_{id}_simulate_clearing.yaml /sandbox/cards/{id}/simulate/return: $ref: paths/sandbox/cards/sandbox_cards_{id}_simulate_return.yaml + /stablecoins: + $ref: paths/stablecoins/stablecoins.yaml + /stablecoins/{stablecoinId}: + $ref: paths/stablecoins/stablecoins_{stablecoinId}.yaml + /stablecoins/{stablecoinId}/mints: + $ref: paths/stablecoins/stablecoins_{stablecoinId}_mints.yaml + /stablecoins/{stablecoinId}/burns: + $ref: paths/stablecoins/stablecoins_{stablecoinId}_burns.yaml + /stablecoins/{stablecoinId}/operations: + $ref: paths/stablecoins/stablecoins_{stablecoinId}_operations.yaml + /stablecoin-operations/{stablecoinOperationId}: + $ref: paths/stablecoins/stablecoin-operations_{stablecoinOperationId}.yaml /stablecoin-provider-accounts: $ref: paths/stablecoins/stablecoin-provider-accounts.yaml /stablecoin-provider-accounts/{stablecoinProviderAccountId}: diff --git a/openapi/paths/stablecoins/stablecoin-operations_{stablecoinOperationId}.yaml b/openapi/paths/stablecoins/stablecoin-operations_{stablecoinOperationId}.yaml new file mode 100644 index 000000000..61ca1eaac --- /dev/null +++ b/openapi/paths/stablecoins/stablecoin-operations_{stablecoinOperationId}.yaml @@ -0,0 +1,40 @@ +parameters: + - name: stablecoinOperationId + in: path + description: System-generated stablecoin issuer operation identifier + required: true + schema: + type: string +get: + summary: Get a stablecoin issuer operation + description: Retrieve a single stablecoin issuer operation by its Grid identifier. + operationId: getStablecoinOperation + tags: + - Stablecoins + security: + - BasicAuth: [] + responses: + '200': + description: Successful operation + content: + application/json: + schema: + $ref: ../../components/schemas/stablecoins/StablecoinOperation.yaml + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: ../../components/schemas/errors/Error401.yaml + '404': + description: Stablecoin operation not found + content: + application/json: + schema: + $ref: ../../components/schemas/errors/Error404.yaml + '500': + description: Internal service error + content: + application/json: + schema: + $ref: ../../components/schemas/errors/Error500.yaml diff --git a/openapi/paths/stablecoins/stablecoins.yaml b/openapi/paths/stablecoins/stablecoins.yaml new file mode 100644 index 000000000..d0b393760 --- /dev/null +++ b/openapi/paths/stablecoins/stablecoins.yaml @@ -0,0 +1,124 @@ +post: + summary: Register an existing provider-created stablecoin + description: | + Register an existing provider-created stablecoin as a Grid `Stablecoin`. This endpoint links provider token metadata to Grid; it does not create the token with the provider. Grid derives the active provider account link from the authenticated platform, provider, and provider environment. + operationId: registerStablecoin + tags: + - Stablecoins + security: + - BasicAuth: [] + parameters: + - name: Idempotency-Key + in: header + description: Required idempotency key for retrying this request safely. + required: true + schema: + type: string + maxLength: 255 + requestBody: + required: true + content: + application/json: + schema: + $ref: ../../components/schemas/stablecoins/StablecoinRegisterRequest.yaml + responses: + '201': + description: Stablecoin registered + content: + application/json: + schema: + $ref: ../../components/schemas/stablecoins/Stablecoin.yaml + '400': + description: Bad request + content: + application/json: + schema: + $ref: ../../components/schemas/errors/Error400.yaml + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: ../../components/schemas/errors/Error401.yaml + '404': + description: Referenced stablecoin provider account not found + content: + application/json: + schema: + $ref: ../../components/schemas/errors/Error404.yaml + '409': + description: Conflict + content: + application/json: + schema: + $ref: ../../components/schemas/errors/Error409.yaml + '500': + description: Internal service error + content: + application/json: + schema: + $ref: ../../components/schemas/errors/Error500.yaml +get: + summary: List stablecoins + description: Retrieve stablecoins registered to the authenticated platform. + operationId: listStablecoins + tags: + - Stablecoins + security: + - BasicAuth: [] + parameters: + - name: issuanceStatus + in: query + required: false + schema: + $ref: ../../components/schemas/stablecoins/StablecoinIssuanceStatus.yaml + - name: gridOperationsStatus + in: query + required: false + schema: + $ref: ../../components/schemas/stablecoins/StablecoinGridOperationsStatus.yaml + - name: provider + in: query + required: false + schema: + $ref: ../../components/schemas/stablecoins/StablecoinProvider.yaml + - name: limit + in: query + description: Maximum number of results to return (default 20, max 100) + required: false + schema: + type: integer + minimum: 1 + maximum: 100 + default: 20 + - name: cursor + in: query + description: Opaque cursor returned as `nextCursor` from the previous response. + required: false + schema: + type: string + responses: + '200': + description: Successful operation + content: + application/json: + schema: + $ref: ../../components/schemas/stablecoins/StablecoinListResponse.yaml + '400': + description: Bad request - Invalid parameters + content: + application/json: + schema: + $ref: ../../components/schemas/errors/Error400.yaml + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: ../../components/schemas/errors/Error401.yaml + '500': + description: Internal service error + content: + application/json: + schema: + $ref: ../../components/schemas/errors/Error500.yaml diff --git a/openapi/paths/stablecoins/stablecoins_{stablecoinId}.yaml b/openapi/paths/stablecoins/stablecoins_{stablecoinId}.yaml new file mode 100644 index 000000000..ad950e02c --- /dev/null +++ b/openapi/paths/stablecoins/stablecoins_{stablecoinId}.yaml @@ -0,0 +1,40 @@ +parameters: + - name: stablecoinId + in: path + description: System-generated stablecoin identifier + required: true + schema: + type: string +get: + summary: Get a stablecoin + description: Retrieve a single registered stablecoin by its Grid identifier. + operationId: getStablecoin + tags: + - Stablecoins + security: + - BasicAuth: [] + responses: + '200': + description: Successful operation + content: + application/json: + schema: + $ref: ../../components/schemas/stablecoins/Stablecoin.yaml + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: ../../components/schemas/errors/Error401.yaml + '404': + description: Stablecoin not found + content: + application/json: + schema: + $ref: ../../components/schemas/errors/Error404.yaml + '500': + description: Internal service error + content: + application/json: + schema: + $ref: ../../components/schemas/errors/Error500.yaml diff --git a/openapi/paths/stablecoins/stablecoins_{stablecoinId}_burns.yaml b/openapi/paths/stablecoins/stablecoins_{stablecoinId}_burns.yaml new file mode 100644 index 000000000..a42795717 --- /dev/null +++ b/openapi/paths/stablecoins/stablecoins_{stablecoinId}_burns.yaml @@ -0,0 +1,73 @@ +parameters: + - name: stablecoinId + in: path + description: System-generated stablecoin identifier + required: true + schema: + type: string +post: + summary: Create a stablecoin burn operation + description: | + Create a provider-backed burn/redemption operation for a registered stablecoin. Burn sources and fiat destinations are normal Grid account objects; provider-specific Brale address ids are resolved and stored internally. External Spark wallet sources return funding instructions and remain pending until the provider reports funds received. + operationId: createStablecoinBurn + tags: + - Stablecoins + security: + - BasicAuth: [] + parameters: + - name: Idempotency-Key + in: header + description: Required idempotency key for retrying this burn request safely. + required: true + schema: + type: string + maxLength: 255 + requestBody: + required: true + content: + application/json: + schema: + $ref: ../../components/schemas/stablecoins/StablecoinBurnRequest.yaml + responses: + '201': + description: Burn operation created + content: + application/json: + schema: + $ref: ../../components/schemas/stablecoins/StablecoinOperation.yaml + '400': + description: Bad request + content: + application/json: + schema: + $ref: ../../components/schemas/errors/Error400.yaml + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: ../../components/schemas/errors/Error401.yaml + '404': + description: Stablecoin or referenced account not found + content: + application/json: + schema: + $ref: ../../components/schemas/errors/Error404.yaml + '409': + description: Conflict + content: + application/json: + schema: + $ref: ../../components/schemas/errors/Error409.yaml + '500': + description: Internal service error + content: + application/json: + schema: + $ref: ../../components/schemas/errors/Error500.yaml + '503': + description: Provider temporarily unavailable + content: + application/json: + schema: + $ref: ../../components/schemas/errors/Error503.yaml diff --git a/openapi/paths/stablecoins/stablecoins_{stablecoinId}_mints.yaml b/openapi/paths/stablecoins/stablecoins_{stablecoinId}_mints.yaml new file mode 100644 index 000000000..cd6dc20eb --- /dev/null +++ b/openapi/paths/stablecoins/stablecoins_{stablecoinId}_mints.yaml @@ -0,0 +1,73 @@ +parameters: + - name: stablecoinId + in: path + description: System-generated stablecoin identifier + required: true + schema: + type: string +post: + summary: Create a stablecoin mint operation + description: | + Create a provider-backed mint operation for a registered stablecoin. Funding and destination accounts are normal Grid `ExternalAccount` objects; any provider-specific Brale address linkage is managed internally by Grid. Wire-funded mints return funding instructions and remain pending until the provider reports funds received. + operationId: createStablecoinMint + tags: + - Stablecoins + security: + - BasicAuth: [] + parameters: + - name: Idempotency-Key + in: header + description: Required idempotency key for retrying this mint request safely. + required: true + schema: + type: string + maxLength: 255 + requestBody: + required: true + content: + application/json: + schema: + $ref: ../../components/schemas/stablecoins/StablecoinMintRequest.yaml + responses: + '201': + description: Mint operation created + content: + application/json: + schema: + $ref: ../../components/schemas/stablecoins/StablecoinOperation.yaml + '400': + description: Bad request + content: + application/json: + schema: + $ref: ../../components/schemas/errors/Error400.yaml + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: ../../components/schemas/errors/Error401.yaml + '404': + description: Stablecoin or referenced account not found + content: + application/json: + schema: + $ref: ../../components/schemas/errors/Error404.yaml + '409': + description: Conflict + content: + application/json: + schema: + $ref: ../../components/schemas/errors/Error409.yaml + '500': + description: Internal service error + content: + application/json: + schema: + $ref: ../../components/schemas/errors/Error500.yaml + '503': + description: Provider temporarily unavailable + content: + application/json: + schema: + $ref: ../../components/schemas/errors/Error503.yaml diff --git a/openapi/paths/stablecoins/stablecoins_{stablecoinId}_operations.yaml b/openapi/paths/stablecoins/stablecoins_{stablecoinId}_operations.yaml new file mode 100644 index 000000000..f65e9702d --- /dev/null +++ b/openapi/paths/stablecoins/stablecoins_{stablecoinId}_operations.yaml @@ -0,0 +1,56 @@ +parameters: + - name: stablecoinId + in: path + description: System-generated stablecoin identifier + required: true + schema: + type: string +get: + summary: List stablecoin issuer operations + description: List issuer mint and burn operations for a stablecoin, most recent first, with cursor pagination. + operationId: listStablecoinOperations + tags: + - Stablecoins + security: + - BasicAuth: [] + parameters: + - name: limit + in: query + description: Maximum number of results to return (default 20, max 100) + required: false + schema: + type: integer + minimum: 1 + maximum: 100 + default: 20 + - name: cursor + in: query + description: Opaque cursor returned as `nextCursor` from the previous response. + required: false + schema: + type: string + responses: + '200': + description: Successful operation + content: + application/json: + schema: + $ref: ../../components/schemas/stablecoins/StablecoinOperationListResponse.yaml + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: ../../components/schemas/errors/Error401.yaml + '404': + description: Stablecoin not found + content: + application/json: + schema: + $ref: ../../components/schemas/errors/Error404.yaml + '500': + description: Internal service error + content: + application/json: + schema: + $ref: ../../components/schemas/errors/Error500.yaml From 3afced11e84c40ff3286c113d09b95350fae0342 Mon Sep 17 00:00:00 2001 From: kphurley7 Date: Wed, 15 Jul 2026 14:02:27 -0500 Subject: [PATCH 2/3] Address stablecoin issuance spec review findings Enforce conditionally-required fields, type the open schemas, add an operations filter, and make operation source naming symmetric. - StablecoinMintFundingSource, StablecoinBurnSource, and StablecoinMintDestination now use the quotes-style oneOf + `type` discriminator with per-variant schemas, so required fields (e.g. externalAccountId for ACH_DEBIT / EXTERNAL_ACCOUNT) are enforced by the schema instead of only being described in prose. StablecoinBurnDestination already unconditionally requires all its fields (single variant), so it is left as-is. - StablecoinFundingInstructions declares its stable fields (rail, network, address, valueType) as typed properties while keeping additionalProperties for rail-specific passthrough, with a comment explaining why it stays open. StablecoinEstimatedDelivery is fully typed (rail, amount, currency, timing). - StablecoinEstimatedDelivery.amount is now expressed in the currency's smallest unit (minor units) to match the rest of the API's money fields. - GET /stablecoins/{stablecoinId}/operations gains an optional operationType query filter. - StablecoinOperation now reports source via a single merged StablecoinOperationSource field (mirroring StablecoinOperationDestination) instead of asymmetric fundingSource/source fields. --- mintlify/openapi.yaml | 349 ++++++++++++++++-- openapi.yaml | 349 ++++++++++++++++-- .../StablecoinAchDebitFundingSource.yaml | 19 + .../stablecoins/StablecoinBurnSource.yaml | 29 +- .../stablecoins/StablecoinBurnSourceBase.yaml | 12 + .../StablecoinEstimatedDelivery.yaml | 20 +- .../StablecoinExternalAccountBurnSource.yaml | 19 + ...blecoinExternalAccountMintDestination.yaml | 19 + .../StablecoinFundingInstructions.yaml | 26 +- .../StablecoinGridInternalBurnSource.yaml | 19 + .../StablecoinGridInternalFundingSource.yaml | 19 + ...StablecoinGridInternalMintDestination.yaml | 19 + .../StablecoinMintDestination.yaml | 26 +- .../StablecoinMintDestinationBase.yaml | 11 + .../StablecoinMintFundingSource.yaml | 43 +-- .../StablecoinMintFundingSourceBase.yaml | 14 + .../stablecoins/StablecoinOperation.yaml | 4 +- .../StablecoinOperationSource.yaml | 40 ++ .../StablecoinProviderBalanceBurnSource.yaml | 14 + ...tablecoinProviderBalanceFundingSource.yaml | 24 ++ ...tablecoinSameDayAchDebitFundingSource.yaml | 19 + .../StablecoinWireFundingSource.yaml | 14 + ...stablecoins_{stablecoinId}_operations.yaml | 6 + 23 files changed, 967 insertions(+), 147 deletions(-) create mode 100644 openapi/components/schemas/stablecoins/StablecoinAchDebitFundingSource.yaml create mode 100644 openapi/components/schemas/stablecoins/StablecoinBurnSourceBase.yaml create mode 100644 openapi/components/schemas/stablecoins/StablecoinExternalAccountBurnSource.yaml create mode 100644 openapi/components/schemas/stablecoins/StablecoinExternalAccountMintDestination.yaml create mode 100644 openapi/components/schemas/stablecoins/StablecoinGridInternalBurnSource.yaml create mode 100644 openapi/components/schemas/stablecoins/StablecoinGridInternalFundingSource.yaml create mode 100644 openapi/components/schemas/stablecoins/StablecoinGridInternalMintDestination.yaml create mode 100644 openapi/components/schemas/stablecoins/StablecoinMintDestinationBase.yaml create mode 100644 openapi/components/schemas/stablecoins/StablecoinMintFundingSourceBase.yaml create mode 100644 openapi/components/schemas/stablecoins/StablecoinOperationSource.yaml create mode 100644 openapi/components/schemas/stablecoins/StablecoinProviderBalanceBurnSource.yaml create mode 100644 openapi/components/schemas/stablecoins/StablecoinProviderBalanceFundingSource.yaml create mode 100644 openapi/components/schemas/stablecoins/StablecoinSameDayAchDebitFundingSource.yaml create mode 100644 openapi/components/schemas/stablecoins/StablecoinWireFundingSource.yaml diff --git a/mintlify/openapi.yaml b/mintlify/openapi.yaml index 9671b1c24..6671a208b 100644 --- a/mintlify/openapi.yaml +++ b/mintlify/openapi.yaml @@ -7812,6 +7812,12 @@ paths: security: - BasicAuth: [] parameters: + - name: operationType + in: query + description: Filter operations by type. When omitted, both mints and burns are returned. + required: false + schema: + $ref: '#/components/schemas/StablecoinOperationType' - name: limit in: query description: Maximum number of results to return (default 20, max 100) @@ -20768,7 +20774,7 @@ components: type: string description: Provider account link to register against. Optional when exactly one active link exists for the authenticated platform; required to resolve STABLECOIN_PROVIDER_ACCOUNT_SELECTION_REQUIRED when multiple links exist. example: StablecoinProviderAccount:019542f5-b3e7-1d02-0000-000000000001 - StablecoinMintFundingSource: + StablecoinMintFundingSourceBase: type: object required: - type @@ -20781,24 +20787,124 @@ components: - SAME_DAY_ACH_DEBIT - GRID_INTERNAL_ACCOUNT - PROVIDER_INTERNAL_BALANCE - description: Funding source variant. For `ACH_DEBIT` and `SAME_DAY_ACH_DEBIT`, `externalAccountId` is required. Grid internal account and provider internal balance funding are reserved for follow-up support. - externalAccountId: - type: string - description: Grid `ExternalAccount` used as the ACH debit funding account. - example: ExternalAccount:019542f5-b3e7-1d02-0000-000000000101 - accountId: - type: string - description: Grid internal funding account id for future Grid-funded mint flows. - example: InternalAccount:019542f5-b3e7-1d02-0000-000000000102 - sourceTokenIdentifier: - type: string - description: Provider token/value type for future provider internal balance funding. - example: USDC - cryptoNetwork: - type: string - description: Source crypto network for future provider internal balance funding. - example: SOLANA - StablecoinMintDestination: + description: Funding source variant. Grid internal account and provider internal balance funding are reserved for follow-up support. + example: ACH_DEBIT + StablecoinWireFundingSource: + title: Wire + allOf: + - $ref: '#/components/schemas/StablecoinMintFundingSourceBase' + - type: object + required: + - type + properties: + type: + type: string + enum: + - WIRE + description: Wire-funded mint. Funding instructions are returned on the resulting operation. + example: WIRE + description: Wire funding source. The issuer wires fiat to the provider using the returned funding instructions. + StablecoinAchDebitFundingSource: + title: ACH Debit + allOf: + - $ref: '#/components/schemas/StablecoinMintFundingSourceBase' + - 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. + StablecoinSameDayAchDebitFundingSource: + title: Same-Day ACH Debit + allOf: + - $ref: '#/components/schemas/StablecoinMintFundingSourceBase' + - type: object + required: + - type + - externalAccountId + properties: + type: + type: string + enum: + - SAME_DAY_ACH_DEBIT + description: Same-day ACH debit funding. + example: SAME_DAY_ACH_DEBIT + externalAccountId: + type: string + description: Grid `ExternalAccount` debited to fund the mint. + example: ExternalAccount:019542f5-b3e7-1d02-0000-000000000101 + description: Same-day ACH debit funding source. The provider debits the referenced external account. + StablecoinGridInternalFundingSource: + title: Grid Internal Account + allOf: + - $ref: '#/components/schemas/StablecoinMintFundingSourceBase' + - 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. + StablecoinProviderBalanceFundingSource: + title: Provider Internal Balance + allOf: + - $ref: '#/components/schemas/StablecoinMintFundingSourceBase' + - type: object + required: + - type + - sourceTokenIdentifier + - cryptoNetwork + properties: + type: + type: string + enum: + - PROVIDER_INTERNAL_BALANCE + description: Provider internal balance funding. Reserved for the follow-up provider-balance mint flow. + example: PROVIDER_INTERNAL_BALANCE + sourceTokenIdentifier: + type: string + description: Provider token/value type spent from the provider internal balance. + example: USDC + cryptoNetwork: + type: string + description: Source crypto network for the provider internal balance funds. + example: SOLANA + description: Provider internal balance funding source, reserved for future provider-funded mint flows. + StablecoinMintFundingSource: + oneOf: + - $ref: '#/components/schemas/StablecoinWireFundingSource' + - $ref: '#/components/schemas/StablecoinAchDebitFundingSource' + - $ref: '#/components/schemas/StablecoinSameDayAchDebitFundingSource' + - $ref: '#/components/schemas/StablecoinGridInternalFundingSource' + - $ref: '#/components/schemas/StablecoinProviderBalanceFundingSource' + discriminator: + propertyName: type + mapping: + WIRE: '#/components/schemas/StablecoinWireFundingSource' + ACH_DEBIT: '#/components/schemas/StablecoinAchDebitFundingSource' + SAME_DAY_ACH_DEBIT: '#/components/schemas/StablecoinSameDayAchDebitFundingSource' + GRID_INTERNAL_ACCOUNT: '#/components/schemas/StablecoinGridInternalFundingSource' + PROVIDER_INTERNAL_BALANCE: '#/components/schemas/StablecoinProviderBalanceFundingSource' + StablecoinMintDestinationBase: type: object required: - type @@ -20809,14 +20915,56 @@ components: - EXTERNAL_ACCOUNT - GRID_INTERNAL_ACCOUNT description: Mint destination variant. In the initial Brale-backed flow, `EXTERNAL_ACCOUNT` must reference an active Spark external account. - externalAccountId: - type: string - description: Grid `ExternalAccount` receiving the minted stablecoin. - example: ExternalAccount:019542f5-b3e7-1d02-0000-000000000201 - accountId: - type: string - description: Grid internal receiving account id for future Grid-managed mint destinations. - example: InternalAccount:019542f5-b3e7-1d02-0000-000000000202 + example: EXTERNAL_ACCOUNT + StablecoinExternalAccountMintDestination: + title: External Account + allOf: + - $ref: '#/components/schemas/StablecoinMintDestinationBase' + - type: object + required: + - type + - externalAccountId + properties: + type: + type: string + enum: + - EXTERNAL_ACCOUNT + description: External account mint destination. Must reference an active Spark external account. + example: EXTERNAL_ACCOUNT + externalAccountId: + type: string + description: Grid `ExternalAccount` receiving the minted stablecoin. + example: ExternalAccount:019542f5-b3e7-1d02-0000-000000000201 + description: External account mint destination. + StablecoinGridInternalMintDestination: + title: Grid Internal Account + allOf: + - $ref: '#/components/schemas/StablecoinMintDestinationBase' + - type: object + required: + - type + - accountId + properties: + type: + type: string + enum: + - GRID_INTERNAL_ACCOUNT + description: Grid internal account mint destination. Reserved for future Grid-managed mint destinations. + example: GRID_INTERNAL_ACCOUNT + accountId: + type: string + description: Grid internal receiving account id. + example: InternalAccount:019542f5-b3e7-1d02-0000-000000000202 + description: Grid internal account mint destination, reserved for future Grid-managed mint destinations. + StablecoinMintDestination: + oneOf: + - $ref: '#/components/schemas/StablecoinExternalAccountMintDestination' + - $ref: '#/components/schemas/StablecoinGridInternalMintDestination' + discriminator: + propertyName: type + mapping: + EXTERNAL_ACCOUNT: '#/components/schemas/StablecoinExternalAccountMintDestination' + GRID_INTERNAL_ACCOUNT: '#/components/schemas/StablecoinGridInternalMintDestination' StablecoinMintRequest: type: object required: @@ -20855,30 +21003,60 @@ components: - FAILED - EXPIRED description: Stablecoin issuer operation lifecycle status. - StablecoinBurnSource: + StablecoinOperationSource: type: object + description: 'Source of a stablecoin operation, as reported on a `StablecoinOperation`. A single merged shape (superset of the mint funding source and burn source request variants) so the field is unambiguously deserializable regardless of operation type: `externalAccountId` is present for external-account funded mints and external-account burns, `accountId` for Grid internal account sources, and `sourceTokenIdentifier`/`cryptoNetwork` for provider internal balance sources.' required: - type properties: type: type: string enum: + - WIRE + - ACH_DEBIT + - SAME_DAY_ACH_DEBIT - EXTERNAL_ACCOUNT - GRID_INTERNAL_ACCOUNT - PROVIDER_INTERNAL_BALANCE - description: Burn source variant. `EXTERNAL_ACCOUNT` references an active Spark external account and returns funding instructions. `PROVIDER_INTERNAL_BALANCE` spends stablecoin funds already at the provider. Grid internal account burns are reserved for the Grid-enabled ledger movement flow. + description: Source variant. Mint funding uses `WIRE`, `ACH_DEBIT`, or `SAME_DAY_ACH_DEBIT`; burns use `EXTERNAL_ACCOUNT`. `GRID_INTERNAL_ACCOUNT` and `PROVIDER_INTERNAL_BALANCE` are shared across mint and burn. + example: ACH_DEBIT externalAccountId: type: string - description: Grid Spark `ExternalAccount` expected to fund the provider for external-source burns. - example: ExternalAccount:019542f5-b3e7-1d02-0000-000000000203 + description: Grid `ExternalAccount` funding the operation, present for ACH debit mints and external-account burns. + example: ExternalAccount:019542f5-b3e7-1d02-0000-000000000101 accountId: type: string - description: Grid internal source account id for future Grid-controlled burn flows. - example: InternalAccount:019542f5-b3e7-1d02-0000-000000000204 + description: Grid internal account id, present for Grid internal account sources. + example: InternalAccount:019542f5-b3e7-1d02-0000-000000000102 + sourceTokenIdentifier: + type: string + description: Provider token/value type, present for provider internal balance sources. + example: USDC + cryptoNetwork: + type: string + description: Source crypto network, present for provider internal balance sources. + example: SOLANA StablecoinFundingInstructions: type: object - description: Provider funding instructions safe to show publicly. Present for wire-funded mint operations and external-source burn operations when available. + 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 @@ -20916,9 +21094,27 @@ components: 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: '1.00' + amount: '100' currency: USD timing: 1-3 business days StablecoinOperation: @@ -20959,10 +21155,8 @@ components: type: string description: Stablecoin provider account link used for the operation. example: StablecoinProviderAccount:019542f5-b3e7-1d02-0000-000000000001 - fundingSource: - $ref: '#/components/schemas/StablecoinMintFundingSource' source: - $ref: '#/components/schemas/StablecoinBurnSource' + $ref: '#/components/schemas/StablecoinOperationSource' fundingInstructions: $ref: '#/components/schemas/StablecoinFundingInstructions' destination: @@ -21023,6 +21217,85 @@ components: type: object description: Additional error details additionalProperties: true + StablecoinBurnSourceBase: + 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 + StablecoinExternalAccountBurnSource: + title: External Account + allOf: + - $ref: '#/components/schemas/StablecoinBurnSourceBase' + - 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. + StablecoinGridInternalBurnSource: + title: Grid Internal Account + allOf: + - $ref: '#/components/schemas/StablecoinBurnSourceBase' + - 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. + StablecoinProviderBalanceBurnSource: + title: Provider Internal Balance + allOf: + - $ref: '#/components/schemas/StablecoinBurnSourceBase' + - type: object + required: + - type + properties: + type: + type: string + enum: + - PROVIDER_INTERNAL_BALANCE + description: Provider internal balance burn. Spends stablecoin funds already held at the provider. + example: PROVIDER_INTERNAL_BALANCE + description: Provider internal balance burn source. No external funding is required; the provider spends existing balance. + StablecoinBurnSource: + oneOf: + - $ref: '#/components/schemas/StablecoinExternalAccountBurnSource' + - $ref: '#/components/schemas/StablecoinGridInternalBurnSource' + - $ref: '#/components/schemas/StablecoinProviderBalanceBurnSource' + discriminator: + propertyName: type + mapping: + EXTERNAL_ACCOUNT: '#/components/schemas/StablecoinExternalAccountBurnSource' + GRID_INTERNAL_ACCOUNT: '#/components/schemas/StablecoinGridInternalBurnSource' + PROVIDER_INTERNAL_BALANCE: '#/components/schemas/StablecoinProviderBalanceBurnSource' StablecoinBurnDestination: type: object required: diff --git a/openapi.yaml b/openapi.yaml index 9671b1c24..6671a208b 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -7812,6 +7812,12 @@ paths: security: - BasicAuth: [] parameters: + - name: operationType + in: query + description: Filter operations by type. When omitted, both mints and burns are returned. + required: false + schema: + $ref: '#/components/schemas/StablecoinOperationType' - name: limit in: query description: Maximum number of results to return (default 20, max 100) @@ -20768,7 +20774,7 @@ components: type: string description: Provider account link to register against. Optional when exactly one active link exists for the authenticated platform; required to resolve STABLECOIN_PROVIDER_ACCOUNT_SELECTION_REQUIRED when multiple links exist. example: StablecoinProviderAccount:019542f5-b3e7-1d02-0000-000000000001 - StablecoinMintFundingSource: + StablecoinMintFundingSourceBase: type: object required: - type @@ -20781,24 +20787,124 @@ components: - SAME_DAY_ACH_DEBIT - GRID_INTERNAL_ACCOUNT - PROVIDER_INTERNAL_BALANCE - description: Funding source variant. For `ACH_DEBIT` and `SAME_DAY_ACH_DEBIT`, `externalAccountId` is required. Grid internal account and provider internal balance funding are reserved for follow-up support. - externalAccountId: - type: string - description: Grid `ExternalAccount` used as the ACH debit funding account. - example: ExternalAccount:019542f5-b3e7-1d02-0000-000000000101 - accountId: - type: string - description: Grid internal funding account id for future Grid-funded mint flows. - example: InternalAccount:019542f5-b3e7-1d02-0000-000000000102 - sourceTokenIdentifier: - type: string - description: Provider token/value type for future provider internal balance funding. - example: USDC - cryptoNetwork: - type: string - description: Source crypto network for future provider internal balance funding. - example: SOLANA - StablecoinMintDestination: + description: Funding source variant. Grid internal account and provider internal balance funding are reserved for follow-up support. + example: ACH_DEBIT + StablecoinWireFundingSource: + title: Wire + allOf: + - $ref: '#/components/schemas/StablecoinMintFundingSourceBase' + - type: object + required: + - type + properties: + type: + type: string + enum: + - WIRE + description: Wire-funded mint. Funding instructions are returned on the resulting operation. + example: WIRE + description: Wire funding source. The issuer wires fiat to the provider using the returned funding instructions. + StablecoinAchDebitFundingSource: + title: ACH Debit + allOf: + - $ref: '#/components/schemas/StablecoinMintFundingSourceBase' + - 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. + StablecoinSameDayAchDebitFundingSource: + title: Same-Day ACH Debit + allOf: + - $ref: '#/components/schemas/StablecoinMintFundingSourceBase' + - type: object + required: + - type + - externalAccountId + properties: + type: + type: string + enum: + - SAME_DAY_ACH_DEBIT + description: Same-day ACH debit funding. + example: SAME_DAY_ACH_DEBIT + externalAccountId: + type: string + description: Grid `ExternalAccount` debited to fund the mint. + example: ExternalAccount:019542f5-b3e7-1d02-0000-000000000101 + description: Same-day ACH debit funding source. The provider debits the referenced external account. + StablecoinGridInternalFundingSource: + title: Grid Internal Account + allOf: + - $ref: '#/components/schemas/StablecoinMintFundingSourceBase' + - 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. + StablecoinProviderBalanceFundingSource: + title: Provider Internal Balance + allOf: + - $ref: '#/components/schemas/StablecoinMintFundingSourceBase' + - type: object + required: + - type + - sourceTokenIdentifier + - cryptoNetwork + properties: + type: + type: string + enum: + - PROVIDER_INTERNAL_BALANCE + description: Provider internal balance funding. Reserved for the follow-up provider-balance mint flow. + example: PROVIDER_INTERNAL_BALANCE + sourceTokenIdentifier: + type: string + description: Provider token/value type spent from the provider internal balance. + example: USDC + cryptoNetwork: + type: string + description: Source crypto network for the provider internal balance funds. + example: SOLANA + description: Provider internal balance funding source, reserved for future provider-funded mint flows. + StablecoinMintFundingSource: + oneOf: + - $ref: '#/components/schemas/StablecoinWireFundingSource' + - $ref: '#/components/schemas/StablecoinAchDebitFundingSource' + - $ref: '#/components/schemas/StablecoinSameDayAchDebitFundingSource' + - $ref: '#/components/schemas/StablecoinGridInternalFundingSource' + - $ref: '#/components/schemas/StablecoinProviderBalanceFundingSource' + discriminator: + propertyName: type + mapping: + WIRE: '#/components/schemas/StablecoinWireFundingSource' + ACH_DEBIT: '#/components/schemas/StablecoinAchDebitFundingSource' + SAME_DAY_ACH_DEBIT: '#/components/schemas/StablecoinSameDayAchDebitFundingSource' + GRID_INTERNAL_ACCOUNT: '#/components/schemas/StablecoinGridInternalFundingSource' + PROVIDER_INTERNAL_BALANCE: '#/components/schemas/StablecoinProviderBalanceFundingSource' + StablecoinMintDestinationBase: type: object required: - type @@ -20809,14 +20915,56 @@ components: - EXTERNAL_ACCOUNT - GRID_INTERNAL_ACCOUNT description: Mint destination variant. In the initial Brale-backed flow, `EXTERNAL_ACCOUNT` must reference an active Spark external account. - externalAccountId: - type: string - description: Grid `ExternalAccount` receiving the minted stablecoin. - example: ExternalAccount:019542f5-b3e7-1d02-0000-000000000201 - accountId: - type: string - description: Grid internal receiving account id for future Grid-managed mint destinations. - example: InternalAccount:019542f5-b3e7-1d02-0000-000000000202 + example: EXTERNAL_ACCOUNT + StablecoinExternalAccountMintDestination: + title: External Account + allOf: + - $ref: '#/components/schemas/StablecoinMintDestinationBase' + - type: object + required: + - type + - externalAccountId + properties: + type: + type: string + enum: + - EXTERNAL_ACCOUNT + description: External account mint destination. Must reference an active Spark external account. + example: EXTERNAL_ACCOUNT + externalAccountId: + type: string + description: Grid `ExternalAccount` receiving the minted stablecoin. + example: ExternalAccount:019542f5-b3e7-1d02-0000-000000000201 + description: External account mint destination. + StablecoinGridInternalMintDestination: + title: Grid Internal Account + allOf: + - $ref: '#/components/schemas/StablecoinMintDestinationBase' + - type: object + required: + - type + - accountId + properties: + type: + type: string + enum: + - GRID_INTERNAL_ACCOUNT + description: Grid internal account mint destination. Reserved for future Grid-managed mint destinations. + example: GRID_INTERNAL_ACCOUNT + accountId: + type: string + description: Grid internal receiving account id. + example: InternalAccount:019542f5-b3e7-1d02-0000-000000000202 + description: Grid internal account mint destination, reserved for future Grid-managed mint destinations. + StablecoinMintDestination: + oneOf: + - $ref: '#/components/schemas/StablecoinExternalAccountMintDestination' + - $ref: '#/components/schemas/StablecoinGridInternalMintDestination' + discriminator: + propertyName: type + mapping: + EXTERNAL_ACCOUNT: '#/components/schemas/StablecoinExternalAccountMintDestination' + GRID_INTERNAL_ACCOUNT: '#/components/schemas/StablecoinGridInternalMintDestination' StablecoinMintRequest: type: object required: @@ -20855,30 +21003,60 @@ components: - FAILED - EXPIRED description: Stablecoin issuer operation lifecycle status. - StablecoinBurnSource: + StablecoinOperationSource: type: object + description: 'Source of a stablecoin operation, as reported on a `StablecoinOperation`. A single merged shape (superset of the mint funding source and burn source request variants) so the field is unambiguously deserializable regardless of operation type: `externalAccountId` is present for external-account funded mints and external-account burns, `accountId` for Grid internal account sources, and `sourceTokenIdentifier`/`cryptoNetwork` for provider internal balance sources.' required: - type properties: type: type: string enum: + - WIRE + - ACH_DEBIT + - SAME_DAY_ACH_DEBIT - EXTERNAL_ACCOUNT - GRID_INTERNAL_ACCOUNT - PROVIDER_INTERNAL_BALANCE - description: Burn source variant. `EXTERNAL_ACCOUNT` references an active Spark external account and returns funding instructions. `PROVIDER_INTERNAL_BALANCE` spends stablecoin funds already at the provider. Grid internal account burns are reserved for the Grid-enabled ledger movement flow. + description: Source variant. Mint funding uses `WIRE`, `ACH_DEBIT`, or `SAME_DAY_ACH_DEBIT`; burns use `EXTERNAL_ACCOUNT`. `GRID_INTERNAL_ACCOUNT` and `PROVIDER_INTERNAL_BALANCE` are shared across mint and burn. + example: ACH_DEBIT externalAccountId: type: string - description: Grid Spark `ExternalAccount` expected to fund the provider for external-source burns. - example: ExternalAccount:019542f5-b3e7-1d02-0000-000000000203 + description: Grid `ExternalAccount` funding the operation, present for ACH debit mints and external-account burns. + example: ExternalAccount:019542f5-b3e7-1d02-0000-000000000101 accountId: type: string - description: Grid internal source account id for future Grid-controlled burn flows. - example: InternalAccount:019542f5-b3e7-1d02-0000-000000000204 + description: Grid internal account id, present for Grid internal account sources. + example: InternalAccount:019542f5-b3e7-1d02-0000-000000000102 + sourceTokenIdentifier: + type: string + description: Provider token/value type, present for provider internal balance sources. + example: USDC + cryptoNetwork: + type: string + description: Source crypto network, present for provider internal balance sources. + example: SOLANA StablecoinFundingInstructions: type: object - description: Provider funding instructions safe to show publicly. Present for wire-funded mint operations and external-source burn operations when available. + 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 @@ -20916,9 +21094,27 @@ components: 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: '1.00' + amount: '100' currency: USD timing: 1-3 business days StablecoinOperation: @@ -20959,10 +21155,8 @@ components: type: string description: Stablecoin provider account link used for the operation. example: StablecoinProviderAccount:019542f5-b3e7-1d02-0000-000000000001 - fundingSource: - $ref: '#/components/schemas/StablecoinMintFundingSource' source: - $ref: '#/components/schemas/StablecoinBurnSource' + $ref: '#/components/schemas/StablecoinOperationSource' fundingInstructions: $ref: '#/components/schemas/StablecoinFundingInstructions' destination: @@ -21023,6 +21217,85 @@ components: type: object description: Additional error details additionalProperties: true + StablecoinBurnSourceBase: + 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 + StablecoinExternalAccountBurnSource: + title: External Account + allOf: + - $ref: '#/components/schemas/StablecoinBurnSourceBase' + - 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. + StablecoinGridInternalBurnSource: + title: Grid Internal Account + allOf: + - $ref: '#/components/schemas/StablecoinBurnSourceBase' + - 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. + StablecoinProviderBalanceBurnSource: + title: Provider Internal Balance + allOf: + - $ref: '#/components/schemas/StablecoinBurnSourceBase' + - type: object + required: + - type + properties: + type: + type: string + enum: + - PROVIDER_INTERNAL_BALANCE + description: Provider internal balance burn. Spends stablecoin funds already held at the provider. + example: PROVIDER_INTERNAL_BALANCE + description: Provider internal balance burn source. No external funding is required; the provider spends existing balance. + StablecoinBurnSource: + oneOf: + - $ref: '#/components/schemas/StablecoinExternalAccountBurnSource' + - $ref: '#/components/schemas/StablecoinGridInternalBurnSource' + - $ref: '#/components/schemas/StablecoinProviderBalanceBurnSource' + discriminator: + propertyName: type + mapping: + EXTERNAL_ACCOUNT: '#/components/schemas/StablecoinExternalAccountBurnSource' + GRID_INTERNAL_ACCOUNT: '#/components/schemas/StablecoinGridInternalBurnSource' + PROVIDER_INTERNAL_BALANCE: '#/components/schemas/StablecoinProviderBalanceBurnSource' StablecoinBurnDestination: type: object required: diff --git a/openapi/components/schemas/stablecoins/StablecoinAchDebitFundingSource.yaml b/openapi/components/schemas/stablecoins/StablecoinAchDebitFundingSource.yaml new file mode 100644 index 000000000..41f143b65 --- /dev/null +++ b/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. diff --git a/openapi/components/schemas/stablecoins/StablecoinBurnSource.yaml b/openapi/components/schemas/stablecoins/StablecoinBurnSource.yaml index 13d766e62..be9721452 100644 --- a/openapi/components/schemas/stablecoins/StablecoinBurnSource.yaml +++ b/openapi/components/schemas/stablecoins/StablecoinBurnSource.yaml @@ -1,19 +1,10 @@ -type: object -required: - - type -properties: - type: - type: string - enum: - - EXTERNAL_ACCOUNT - - GRID_INTERNAL_ACCOUNT - - PROVIDER_INTERNAL_BALANCE - description: Burn source variant. `EXTERNAL_ACCOUNT` references an active Spark external account and returns funding instructions. `PROVIDER_INTERNAL_BALANCE` spends stablecoin funds already at the provider. Grid internal account burns are reserved for the Grid-enabled ledger movement flow. - externalAccountId: - type: string - description: Grid Spark `ExternalAccount` expected to fund the provider for external-source burns. - example: ExternalAccount:019542f5-b3e7-1d02-0000-000000000203 - accountId: - type: string - description: Grid internal source account id for future Grid-controlled burn flows. - example: InternalAccount:019542f5-b3e7-1d02-0000-000000000204 +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 diff --git a/openapi/components/schemas/stablecoins/StablecoinBurnSourceBase.yaml b/openapi/components/schemas/stablecoins/StablecoinBurnSourceBase.yaml new file mode 100644 index 000000000..cf2123ce1 --- /dev/null +++ b/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 diff --git a/openapi/components/schemas/stablecoins/StablecoinEstimatedDelivery.yaml b/openapi/components/schemas/stablecoins/StablecoinEstimatedDelivery.yaml index eeb292e71..774cc0e9c 100644 --- a/openapi/components/schemas/stablecoins/StablecoinEstimatedDelivery.yaml +++ b/openapi/components/schemas/stablecoins/StablecoinEstimatedDelivery.yaml @@ -1,8 +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: '1.00' + amount: '100' currency: USD timing: 1-3 business days diff --git a/openapi/components/schemas/stablecoins/StablecoinExternalAccountBurnSource.yaml b/openapi/components/schemas/stablecoins/StablecoinExternalAccountBurnSource.yaml new file mode 100644 index 000000000..96fff4de3 --- /dev/null +++ b/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. diff --git a/openapi/components/schemas/stablecoins/StablecoinExternalAccountMintDestination.yaml b/openapi/components/schemas/stablecoins/StablecoinExternalAccountMintDestination.yaml new file mode 100644 index 000000000..1dca3216f --- /dev/null +++ b/openapi/components/schemas/stablecoins/StablecoinExternalAccountMintDestination.yaml @@ -0,0 +1,19 @@ +title: External Account +allOf: + - $ref: ./StablecoinMintDestinationBase.yaml + - type: object + required: + - type + - externalAccountId + properties: + type: + type: string + enum: + - EXTERNAL_ACCOUNT + description: External account mint destination. Must reference an active Spark external account. + example: EXTERNAL_ACCOUNT + externalAccountId: + type: string + description: Grid `ExternalAccount` receiving the minted stablecoin. + example: ExternalAccount:019542f5-b3e7-1d02-0000-000000000201 + description: External account mint destination. diff --git a/openapi/components/schemas/stablecoins/StablecoinFundingInstructions.yaml b/openapi/components/schemas/stablecoins/StablecoinFundingInstructions.yaml index d9184dc0d..98cf74260 100644 --- a/openapi/components/schemas/stablecoins/StablecoinFundingInstructions.yaml +++ b/openapi/components/schemas/stablecoins/StablecoinFundingInstructions.yaml @@ -1,6 +1,30 @@ type: object -description: Provider funding instructions safe to show publicly. Present for wire-funded mint operations and external-source burn operations when available. +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 diff --git a/openapi/components/schemas/stablecoins/StablecoinGridInternalBurnSource.yaml b/openapi/components/schemas/stablecoins/StablecoinGridInternalBurnSource.yaml new file mode 100644 index 000000000..e98be75c1 --- /dev/null +++ b/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. diff --git a/openapi/components/schemas/stablecoins/StablecoinGridInternalFundingSource.yaml b/openapi/components/schemas/stablecoins/StablecoinGridInternalFundingSource.yaml new file mode 100644 index 000000000..aa3d50dbd --- /dev/null +++ b/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. diff --git a/openapi/components/schemas/stablecoins/StablecoinGridInternalMintDestination.yaml b/openapi/components/schemas/stablecoins/StablecoinGridInternalMintDestination.yaml new file mode 100644 index 000000000..9da969cc8 --- /dev/null +++ b/openapi/components/schemas/stablecoins/StablecoinGridInternalMintDestination.yaml @@ -0,0 +1,19 @@ +title: Grid Internal Account +allOf: + - $ref: ./StablecoinMintDestinationBase.yaml + - type: object + required: + - type + - accountId + properties: + type: + type: string + enum: + - GRID_INTERNAL_ACCOUNT + description: Grid internal account mint destination. Reserved for future Grid-managed mint destinations. + example: GRID_INTERNAL_ACCOUNT + accountId: + type: string + description: Grid internal receiving account id. + example: InternalAccount:019542f5-b3e7-1d02-0000-000000000202 + description: Grid internal account mint destination, reserved for future Grid-managed mint destinations. diff --git a/openapi/components/schemas/stablecoins/StablecoinMintDestination.yaml b/openapi/components/schemas/stablecoins/StablecoinMintDestination.yaml index 60f50a568..debfa29a9 100644 --- a/openapi/components/schemas/stablecoins/StablecoinMintDestination.yaml +++ b/openapi/components/schemas/stablecoins/StablecoinMintDestination.yaml @@ -1,18 +1,8 @@ -type: object -required: - - type -properties: - type: - type: string - enum: - - EXTERNAL_ACCOUNT - - GRID_INTERNAL_ACCOUNT - description: Mint destination variant. In the initial Brale-backed flow, `EXTERNAL_ACCOUNT` must reference an active Spark external account. - externalAccountId: - type: string - description: Grid `ExternalAccount` receiving the minted stablecoin. - example: ExternalAccount:019542f5-b3e7-1d02-0000-000000000201 - accountId: - type: string - description: Grid internal receiving account id for future Grid-managed mint destinations. - example: InternalAccount:019542f5-b3e7-1d02-0000-000000000202 +oneOf: + - $ref: ./StablecoinExternalAccountMintDestination.yaml + - $ref: ./StablecoinGridInternalMintDestination.yaml +discriminator: + propertyName: type + mapping: + EXTERNAL_ACCOUNT: ./StablecoinExternalAccountMintDestination.yaml + GRID_INTERNAL_ACCOUNT: ./StablecoinGridInternalMintDestination.yaml diff --git a/openapi/components/schemas/stablecoins/StablecoinMintDestinationBase.yaml b/openapi/components/schemas/stablecoins/StablecoinMintDestinationBase.yaml new file mode 100644 index 000000000..bf0257071 --- /dev/null +++ b/openapi/components/schemas/stablecoins/StablecoinMintDestinationBase.yaml @@ -0,0 +1,11 @@ +type: object +required: + - type +properties: + type: + type: string + enum: + - EXTERNAL_ACCOUNT + - GRID_INTERNAL_ACCOUNT + description: Mint destination variant. In the initial Brale-backed flow, `EXTERNAL_ACCOUNT` must reference an active Spark external account. + example: EXTERNAL_ACCOUNT diff --git a/openapi/components/schemas/stablecoins/StablecoinMintFundingSource.yaml b/openapi/components/schemas/stablecoins/StablecoinMintFundingSource.yaml index ce0d30684..0b6dc1ec6 100644 --- a/openapi/components/schemas/stablecoins/StablecoinMintFundingSource.yaml +++ b/openapi/components/schemas/stablecoins/StablecoinMintFundingSource.yaml @@ -1,29 +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. For `ACH_DEBIT` and `SAME_DAY_ACH_DEBIT`, `externalAccountId` is required. Grid internal account and provider internal balance funding are reserved for follow-up support. - externalAccountId: - type: string - description: Grid `ExternalAccount` used as the ACH debit funding account. - example: ExternalAccount:019542f5-b3e7-1d02-0000-000000000101 - accountId: - type: string - description: Grid internal funding account id for future Grid-funded mint flows. - example: InternalAccount:019542f5-b3e7-1d02-0000-000000000102 - sourceTokenIdentifier: - type: string - description: Provider token/value type for future provider internal balance funding. - example: USDC - cryptoNetwork: - type: string - description: Source crypto network for future provider internal balance funding. - example: SOLANA +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 diff --git a/openapi/components/schemas/stablecoins/StablecoinMintFundingSourceBase.yaml b/openapi/components/schemas/stablecoins/StablecoinMintFundingSourceBase.yaml new file mode 100644 index 000000000..09c2ca0e4 --- /dev/null +++ b/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 diff --git a/openapi/components/schemas/stablecoins/StablecoinOperation.yaml b/openapi/components/schemas/stablecoins/StablecoinOperation.yaml index 1a0c28f5f..068ed5594 100644 --- a/openapi/components/schemas/stablecoins/StablecoinOperation.yaml +++ b/openapi/components/schemas/stablecoins/StablecoinOperation.yaml @@ -35,10 +35,8 @@ properties: type: string description: Stablecoin provider account link used for the operation. example: StablecoinProviderAccount:019542f5-b3e7-1d02-0000-000000000001 - fundingSource: - $ref: StablecoinMintFundingSource.yaml source: - $ref: StablecoinBurnSource.yaml + $ref: StablecoinOperationSource.yaml fundingInstructions: $ref: StablecoinFundingInstructions.yaml destination: diff --git a/openapi/components/schemas/stablecoins/StablecoinOperationSource.yaml b/openapi/components/schemas/stablecoins/StablecoinOperationSource.yaml new file mode 100644 index 000000000..3d2edb9a9 --- /dev/null +++ b/openapi/components/schemas/stablecoins/StablecoinOperationSource.yaml @@ -0,0 +1,40 @@ +type: object +description: >- + Source of a stablecoin operation, as reported on a + `StablecoinOperation`. A single merged shape (superset of the + mint funding source and burn source request variants) so the field + is unambiguously deserializable regardless of operation type: + `externalAccountId` is present for external-account funded mints and + external-account burns, `accountId` for Grid internal account + sources, and `sourceTokenIdentifier`/`cryptoNetwork` for provider + internal balance sources. +required: + - type +properties: + type: + type: string + enum: + - WIRE + - ACH_DEBIT + - SAME_DAY_ACH_DEBIT + - EXTERNAL_ACCOUNT + - GRID_INTERNAL_ACCOUNT + - PROVIDER_INTERNAL_BALANCE + description: Source variant. Mint funding uses `WIRE`, `ACH_DEBIT`, or `SAME_DAY_ACH_DEBIT`; burns use `EXTERNAL_ACCOUNT`. `GRID_INTERNAL_ACCOUNT` and `PROVIDER_INTERNAL_BALANCE` are shared across mint and burn. + example: ACH_DEBIT + externalAccountId: + type: string + description: Grid `ExternalAccount` funding the operation, present for ACH debit mints and external-account burns. + example: ExternalAccount:019542f5-b3e7-1d02-0000-000000000101 + accountId: + type: string + description: Grid internal account id, present for Grid internal account sources. + example: InternalAccount:019542f5-b3e7-1d02-0000-000000000102 + sourceTokenIdentifier: + type: string + description: Provider token/value type, present for provider internal balance sources. + example: USDC + cryptoNetwork: + type: string + description: Source crypto network, present for provider internal balance sources. + example: SOLANA diff --git a/openapi/components/schemas/stablecoins/StablecoinProviderBalanceBurnSource.yaml b/openapi/components/schemas/stablecoins/StablecoinProviderBalanceBurnSource.yaml new file mode 100644 index 000000000..f3e7cd1a3 --- /dev/null +++ b/openapi/components/schemas/stablecoins/StablecoinProviderBalanceBurnSource.yaml @@ -0,0 +1,14 @@ +title: Provider Internal Balance +allOf: + - $ref: ./StablecoinBurnSourceBase.yaml + - type: object + required: + - type + properties: + type: + type: string + enum: + - PROVIDER_INTERNAL_BALANCE + description: Provider internal balance burn. Spends stablecoin funds already held at the provider. + example: PROVIDER_INTERNAL_BALANCE + description: Provider internal balance burn source. No external funding is required; the provider spends existing balance. diff --git a/openapi/components/schemas/stablecoins/StablecoinProviderBalanceFundingSource.yaml b/openapi/components/schemas/stablecoins/StablecoinProviderBalanceFundingSource.yaml new file mode 100644 index 000000000..458608c27 --- /dev/null +++ b/openapi/components/schemas/stablecoins/StablecoinProviderBalanceFundingSource.yaml @@ -0,0 +1,24 @@ +title: Provider Internal Balance +allOf: + - $ref: ./StablecoinMintFundingSourceBase.yaml + - type: object + required: + - type + - sourceTokenIdentifier + - cryptoNetwork + properties: + type: + type: string + enum: + - PROVIDER_INTERNAL_BALANCE + description: Provider internal balance funding. Reserved for the follow-up provider-balance mint flow. + example: PROVIDER_INTERNAL_BALANCE + sourceTokenIdentifier: + type: string + description: Provider token/value type spent from the provider internal balance. + example: USDC + cryptoNetwork: + type: string + description: Source crypto network for the provider internal balance funds. + example: SOLANA + description: Provider internal balance funding source, reserved for future provider-funded mint flows. diff --git a/openapi/components/schemas/stablecoins/StablecoinSameDayAchDebitFundingSource.yaml b/openapi/components/schemas/stablecoins/StablecoinSameDayAchDebitFundingSource.yaml new file mode 100644 index 000000000..2a3e1c470 --- /dev/null +++ b/openapi/components/schemas/stablecoins/StablecoinSameDayAchDebitFundingSource.yaml @@ -0,0 +1,19 @@ +title: Same-Day ACH Debit +allOf: + - $ref: ./StablecoinMintFundingSourceBase.yaml + - type: object + required: + - type + - externalAccountId + properties: + type: + type: string + enum: + - SAME_DAY_ACH_DEBIT + description: Same-day ACH debit funding. + example: SAME_DAY_ACH_DEBIT + externalAccountId: + type: string + description: Grid `ExternalAccount` debited to fund the mint. + example: ExternalAccount:019542f5-b3e7-1d02-0000-000000000101 + description: Same-day ACH debit funding source. The provider debits the referenced external account. diff --git a/openapi/components/schemas/stablecoins/StablecoinWireFundingSource.yaml b/openapi/components/schemas/stablecoins/StablecoinWireFundingSource.yaml new file mode 100644 index 000000000..752f33788 --- /dev/null +++ b/openapi/components/schemas/stablecoins/StablecoinWireFundingSource.yaml @@ -0,0 +1,14 @@ +title: Wire +allOf: + - $ref: ./StablecoinMintFundingSourceBase.yaml + - type: object + required: + - type + properties: + type: + type: string + enum: + - WIRE + description: Wire-funded mint. Funding instructions are returned on the resulting operation. + example: WIRE + description: Wire funding source. The issuer wires fiat to the provider using the returned funding instructions. diff --git a/openapi/paths/stablecoins/stablecoins_{stablecoinId}_operations.yaml b/openapi/paths/stablecoins/stablecoins_{stablecoinId}_operations.yaml index f65e9702d..18dd93307 100644 --- a/openapi/paths/stablecoins/stablecoins_{stablecoinId}_operations.yaml +++ b/openapi/paths/stablecoins/stablecoins_{stablecoinId}_operations.yaml @@ -14,6 +14,12 @@ get: security: - BasicAuth: [] parameters: + - name: operationType + in: query + description: Filter operations by type. When omitted, both mints and burns are returned. + required: false + schema: + $ref: ../../components/schemas/stablecoins/StablecoinOperationType.yaml - name: limit in: query description: Maximum number of results to return (default 20, max 100) From 227eedb95e65d1f98e975b7338aa045f58dd3646 Mon Sep 17 00:00:00 2001 From: kphurley7 Date: Thu, 16 Jul 2026 08:57:48 -0500 Subject: [PATCH 3/3] Unify stablecoin mint/operation destinations to a single accountId Address shreyav review on the stablecoin issuance spec: represent internal and external accounts as one `account` reference instead of an internal/external discriminator, matching the existing AccountDestination / AccountQuoteSource / AccountTransactionDestination pattern where the id prefix (`ExternalAccount:` / `InternalAccount:`) disambiguates. - StablecoinMintDestination: collapse the oneOf + type=EXTERNAL_ACCOUNT|GRID_INTERNAL_ACCOUNT discriminator (and its StablecoinExternalAccountMintDestination / StablecoinGridInternalMintDestination / StablecoinMintDestinationBase variants) into a single object with one required `accountId`. Also removes the conditionally-required-fields concern since a single always-required field has no conditional case. - StablecoinOperationDestination: merge externalAccountId/accountId into a single `accountId` and drop the now-redundant external/internal `type` (the id prefix carries it). Keeps the flat, non-oneOf merged shape; `rail` still distinguishes burn (fiat payout) from mint destinations. Regenerated openapi.yaml and mintlify/openapi.yaml via redocly bundle. --- mintlify/openapi.yaml | 81 +++---------------- openapi.yaml | 81 +++---------------- ...blecoinExternalAccountMintDestination.yaml | 19 ----- ...StablecoinGridInternalMintDestination.yaml | 19 ----- .../StablecoinMintDestination.yaml | 26 ++++-- .../StablecoinMintDestinationBase.yaml | 11 --- .../StablecoinOperationDestination.yaml | 30 +++---- 7 files changed, 50 insertions(+), 217 deletions(-) delete mode 100644 openapi/components/schemas/stablecoins/StablecoinExternalAccountMintDestination.yaml delete mode 100644 openapi/components/schemas/stablecoins/StablecoinGridInternalMintDestination.yaml delete mode 100644 openapi/components/schemas/stablecoins/StablecoinMintDestinationBase.yaml diff --git a/mintlify/openapi.yaml b/mintlify/openapi.yaml index 6671a208b..c591121db 100644 --- a/mintlify/openapi.yaml +++ b/mintlify/openapi.yaml @@ -20904,67 +20904,16 @@ components: SAME_DAY_ACH_DEBIT: '#/components/schemas/StablecoinSameDayAchDebitFundingSource' GRID_INTERNAL_ACCOUNT: '#/components/schemas/StablecoinGridInternalFundingSource' PROVIDER_INTERNAL_BALANCE: '#/components/schemas/StablecoinProviderBalanceFundingSource' - StablecoinMintDestinationBase: + StablecoinMintDestination: 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: - - type + - accountId properties: - type: + accountId: type: string - enum: - - EXTERNAL_ACCOUNT - - GRID_INTERNAL_ACCOUNT - description: Mint destination variant. In the initial Brale-backed flow, `EXTERNAL_ACCOUNT` must reference an active Spark external account. - example: EXTERNAL_ACCOUNT - StablecoinExternalAccountMintDestination: - title: External Account - allOf: - - $ref: '#/components/schemas/StablecoinMintDestinationBase' - - type: object - required: - - type - - externalAccountId - properties: - type: - type: string - enum: - - EXTERNAL_ACCOUNT - description: External account mint destination. Must reference an active Spark external account. - example: EXTERNAL_ACCOUNT - externalAccountId: - type: string - description: Grid `ExternalAccount` receiving the minted stablecoin. - example: ExternalAccount:019542f5-b3e7-1d02-0000-000000000201 - description: External account mint destination. - StablecoinGridInternalMintDestination: - title: Grid Internal Account - allOf: - - $ref: '#/components/schemas/StablecoinMintDestinationBase' - - type: object - required: - - type - - accountId - properties: - type: - type: string - enum: - - GRID_INTERNAL_ACCOUNT - description: Grid internal account mint destination. Reserved for future Grid-managed mint destinations. - example: GRID_INTERNAL_ACCOUNT - accountId: - type: string - description: Grid internal receiving account id. - example: InternalAccount:019542f5-b3e7-1d02-0000-000000000202 - description: Grid internal account mint destination, reserved for future Grid-managed mint destinations. - StablecoinMintDestination: - oneOf: - - $ref: '#/components/schemas/StablecoinExternalAccountMintDestination' - - $ref: '#/components/schemas/StablecoinGridInternalMintDestination' - discriminator: - propertyName: type - mapping: - EXTERNAL_ACCOUNT: '#/components/schemas/StablecoinExternalAccountMintDestination' - GRID_INTERNAL_ACCOUNT: '#/components/schemas/StablecoinGridInternalMintDestination' + 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 StablecoinMintRequest: type: object required: @@ -21064,24 +21013,14 @@ components: valueType: ACME StablecoinOperationDestination: type: object - description: 'Destination of a stablecoin operation, as reported on a `StablecoinOperation`. A single merged shape (superset of the mint and burn destination request variants) so the field is unambiguously deserializable regardless of operation type: `rail` is present for burn (fiat payout) destinations and absent for mint destinations.' + description: 'Destination of a stablecoin operation, as reported on a `StablecoinOperation`. A single merged (flat) shape so the field is unambiguously deserializable regardless of operation type: `accountId` identifies the receiving account (its `ExternalAccount:` / `InternalAccount:` prefix disambiguates external vs Grid-managed), and `rail` is present for burn (fiat payout) destinations and absent for mint destinations.' required: - - type + - accountId properties: - type: - type: string - enum: - - EXTERNAL_ACCOUNT - - GRID_INTERNAL_ACCOUNT - description: Destination variant. - externalAccountId: - type: string - description: Grid `ExternalAccount` id, when the destination is an external account. - example: ExternalAccount:019542f5-b3e7-1d02-0000-000000000205 accountId: type: string - description: Grid internal account id, when the destination is a Grid-managed account. - example: InternalAccount:019542f5-b3e7-1d02-0000-000000000202 + description: Grid account that received the funds. An `ExternalAccount:` id for external destinations or an `InternalAccount:` id for Grid-managed destinations. + example: ExternalAccount:019542f5-b3e7-1d02-0000-000000000205 rail: type: string enum: diff --git a/openapi.yaml b/openapi.yaml index 6671a208b..c591121db 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -20904,67 +20904,16 @@ components: SAME_DAY_ACH_DEBIT: '#/components/schemas/StablecoinSameDayAchDebitFundingSource' GRID_INTERNAL_ACCOUNT: '#/components/schemas/StablecoinGridInternalFundingSource' PROVIDER_INTERNAL_BALANCE: '#/components/schemas/StablecoinProviderBalanceFundingSource' - StablecoinMintDestinationBase: + StablecoinMintDestination: 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: - - type + - accountId properties: - type: + accountId: type: string - enum: - - EXTERNAL_ACCOUNT - - GRID_INTERNAL_ACCOUNT - description: Mint destination variant. In the initial Brale-backed flow, `EXTERNAL_ACCOUNT` must reference an active Spark external account. - example: EXTERNAL_ACCOUNT - StablecoinExternalAccountMintDestination: - title: External Account - allOf: - - $ref: '#/components/schemas/StablecoinMintDestinationBase' - - type: object - required: - - type - - externalAccountId - properties: - type: - type: string - enum: - - EXTERNAL_ACCOUNT - description: External account mint destination. Must reference an active Spark external account. - example: EXTERNAL_ACCOUNT - externalAccountId: - type: string - description: Grid `ExternalAccount` receiving the minted stablecoin. - example: ExternalAccount:019542f5-b3e7-1d02-0000-000000000201 - description: External account mint destination. - StablecoinGridInternalMintDestination: - title: Grid Internal Account - allOf: - - $ref: '#/components/schemas/StablecoinMintDestinationBase' - - type: object - required: - - type - - accountId - properties: - type: - type: string - enum: - - GRID_INTERNAL_ACCOUNT - description: Grid internal account mint destination. Reserved for future Grid-managed mint destinations. - example: GRID_INTERNAL_ACCOUNT - accountId: - type: string - description: Grid internal receiving account id. - example: InternalAccount:019542f5-b3e7-1d02-0000-000000000202 - description: Grid internal account mint destination, reserved for future Grid-managed mint destinations. - StablecoinMintDestination: - oneOf: - - $ref: '#/components/schemas/StablecoinExternalAccountMintDestination' - - $ref: '#/components/schemas/StablecoinGridInternalMintDestination' - discriminator: - propertyName: type - mapping: - EXTERNAL_ACCOUNT: '#/components/schemas/StablecoinExternalAccountMintDestination' - GRID_INTERNAL_ACCOUNT: '#/components/schemas/StablecoinGridInternalMintDestination' + 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 StablecoinMintRequest: type: object required: @@ -21064,24 +21013,14 @@ components: valueType: ACME StablecoinOperationDestination: type: object - description: 'Destination of a stablecoin operation, as reported on a `StablecoinOperation`. A single merged shape (superset of the mint and burn destination request variants) so the field is unambiguously deserializable regardless of operation type: `rail` is present for burn (fiat payout) destinations and absent for mint destinations.' + description: 'Destination of a stablecoin operation, as reported on a `StablecoinOperation`. A single merged (flat) shape so the field is unambiguously deserializable regardless of operation type: `accountId` identifies the receiving account (its `ExternalAccount:` / `InternalAccount:` prefix disambiguates external vs Grid-managed), and `rail` is present for burn (fiat payout) destinations and absent for mint destinations.' required: - - type + - accountId properties: - type: - type: string - enum: - - EXTERNAL_ACCOUNT - - GRID_INTERNAL_ACCOUNT - description: Destination variant. - externalAccountId: - type: string - description: Grid `ExternalAccount` id, when the destination is an external account. - example: ExternalAccount:019542f5-b3e7-1d02-0000-000000000205 accountId: type: string - description: Grid internal account id, when the destination is a Grid-managed account. - example: InternalAccount:019542f5-b3e7-1d02-0000-000000000202 + description: Grid account that received the funds. An `ExternalAccount:` id for external destinations or an `InternalAccount:` id for Grid-managed destinations. + example: ExternalAccount:019542f5-b3e7-1d02-0000-000000000205 rail: type: string enum: diff --git a/openapi/components/schemas/stablecoins/StablecoinExternalAccountMintDestination.yaml b/openapi/components/schemas/stablecoins/StablecoinExternalAccountMintDestination.yaml deleted file mode 100644 index 1dca3216f..000000000 --- a/openapi/components/schemas/stablecoins/StablecoinExternalAccountMintDestination.yaml +++ /dev/null @@ -1,19 +0,0 @@ -title: External Account -allOf: - - $ref: ./StablecoinMintDestinationBase.yaml - - type: object - required: - - type - - externalAccountId - properties: - type: - type: string - enum: - - EXTERNAL_ACCOUNT - description: External account mint destination. Must reference an active Spark external account. - example: EXTERNAL_ACCOUNT - externalAccountId: - type: string - description: Grid `ExternalAccount` receiving the minted stablecoin. - example: ExternalAccount:019542f5-b3e7-1d02-0000-000000000201 - description: External account mint destination. diff --git a/openapi/components/schemas/stablecoins/StablecoinGridInternalMintDestination.yaml b/openapi/components/schemas/stablecoins/StablecoinGridInternalMintDestination.yaml deleted file mode 100644 index 9da969cc8..000000000 --- a/openapi/components/schemas/stablecoins/StablecoinGridInternalMintDestination.yaml +++ /dev/null @@ -1,19 +0,0 @@ -title: Grid Internal Account -allOf: - - $ref: ./StablecoinMintDestinationBase.yaml - - type: object - required: - - type - - accountId - properties: - type: - type: string - enum: - - GRID_INTERNAL_ACCOUNT - description: Grid internal account mint destination. Reserved for future Grid-managed mint destinations. - example: GRID_INTERNAL_ACCOUNT - accountId: - type: string - description: Grid internal receiving account id. - example: InternalAccount:019542f5-b3e7-1d02-0000-000000000202 - description: Grid internal account mint destination, reserved for future Grid-managed mint destinations. diff --git a/openapi/components/schemas/stablecoins/StablecoinMintDestination.yaml b/openapi/components/schemas/stablecoins/StablecoinMintDestination.yaml index debfa29a9..970a69891 100644 --- a/openapi/components/schemas/stablecoins/StablecoinMintDestination.yaml +++ b/openapi/components/schemas/stablecoins/StablecoinMintDestination.yaml @@ -1,8 +1,18 @@ -oneOf: - - $ref: ./StablecoinExternalAccountMintDestination.yaml - - $ref: ./StablecoinGridInternalMintDestination.yaml -discriminator: - propertyName: type - mapping: - EXTERNAL_ACCOUNT: ./StablecoinExternalAccountMintDestination.yaml - GRID_INTERNAL_ACCOUNT: ./StablecoinGridInternalMintDestination.yaml +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 diff --git a/openapi/components/schemas/stablecoins/StablecoinMintDestinationBase.yaml b/openapi/components/schemas/stablecoins/StablecoinMintDestinationBase.yaml deleted file mode 100644 index bf0257071..000000000 --- a/openapi/components/schemas/stablecoins/StablecoinMintDestinationBase.yaml +++ /dev/null @@ -1,11 +0,0 @@ -type: object -required: - - type -properties: - type: - type: string - enum: - - EXTERNAL_ACCOUNT - - GRID_INTERNAL_ACCOUNT - description: Mint destination variant. In the initial Brale-backed flow, `EXTERNAL_ACCOUNT` must reference an active Spark external account. - example: EXTERNAL_ACCOUNT diff --git a/openapi/components/schemas/stablecoins/StablecoinOperationDestination.yaml b/openapi/components/schemas/stablecoins/StablecoinOperationDestination.yaml index 908bc02ec..c6fe86c64 100644 --- a/openapi/components/schemas/stablecoins/StablecoinOperationDestination.yaml +++ b/openapi/components/schemas/stablecoins/StablecoinOperationDestination.yaml @@ -1,28 +1,22 @@ type: object description: >- Destination of a stablecoin operation, as reported on a - `StablecoinOperation`. A single merged shape (superset of the - mint and burn destination request variants) so the field is - unambiguously deserializable regardless of operation type: `rail` - is present for burn (fiat payout) destinations and absent for mint - destinations. + `StablecoinOperation`. A single merged (flat) shape so the field is + unambiguously deserializable regardless of operation type: `accountId` + identifies the receiving account (its `ExternalAccount:` / + `InternalAccount:` prefix disambiguates external vs Grid-managed), and + `rail` is present for burn (fiat payout) destinations and absent for + mint destinations. required: - - type + - accountId properties: - type: - type: string - enum: - - EXTERNAL_ACCOUNT - - GRID_INTERNAL_ACCOUNT - description: Destination variant. - externalAccountId: - type: string - description: Grid `ExternalAccount` id, when the destination is an external account. - example: ExternalAccount:019542f5-b3e7-1d02-0000-000000000205 accountId: type: string - description: Grid internal account id, when the destination is a Grid-managed account. - example: InternalAccount:019542f5-b3e7-1d02-0000-000000000202 + description: >- + Grid account that received the funds. An `ExternalAccount:` id for + external destinations or an `InternalAccount:` id for Grid-managed + destinations. + example: ExternalAccount:019542f5-b3e7-1d02-0000-000000000205 rail: type: string enum: