Mesh Catalog Gas Sponsorship API

openapi: 3.2.0
info:
  title: Mesh Connect Integration Catalog Gas Sponsorship API
  description: 'Mesh allows users to connect accounts of financial institutions,

    crypto exchanges, and self-custody wallets. Mesh handles credential

    validation, MFA, and error handling for each integration. After

    an account is connected, Mesh allows client applications to read holdings,

    transaction history and balances and execute crypto transfers (with user approval).'
  version: '1.0'
servers:
- url: https://integration-api.meshconnect.com
- url: https://sandbox-integration-api.meshconnect.com
security:
- Client-Secret: []
  Client-Id: []
tags:
- name: CatalogGasSponsorship
paths:
  /api/v1/sponsorship/build:
    post:
      tags:
      - CatalogGasSponsorship
      summary: Build a sponsored transaction payload for the client to sign
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/BuildSponsorshipRequestBody'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuildSponsoredTxResponseApiResult'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema: {}
      operationId: postApiV1SponsorshipBuild
      x-operation-id-source: derived
  /api/v1/sponsorship/submit:
    post:
      tags:
      - CatalogGasSponsorship
      summary: Submit a client-signed sponsored transaction for broadcast
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/SubmitSponsorshipRequestBody'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitSponsoredTxResponseApiResult'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema: {}
      operationId: postApiV1SponsorshipSubmit
      x-operation-id-source: derived
  /api/v1/sponsorship/{trackingId}:
    get:
      tags:
      - CatalogGasSponsorship
      summary: Get the current status of a sponsored transaction
      parameters:
      - name: trackingId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SponsoredTxStatusApiResult'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema: {}
      operationId: getApiV1SponsorshipByTrackingId
      x-operation-id-source: derived
components:
  schemas:
    SponsoredTxStatus:
      type: object
      properties:
        trackingId:
          type: string
          description: Ledger tracking id correlating the request to its persisted entry.
          format: uuid
        strategy:
          enum:
          - unknown
          - metaMaskGasIncluded
          - alchemySolanaFeePayer
          - relayLinkEvmFeeSponsor
          allOf:
          - $ref: '#/components/schemas/GasSponsorshipStrategyKind'
          description: Sponsorship strategy that produced this status.
        state:
          enum:
          - unknown
          - built
          - submitted
          - confirmed
          - failed
          - cancelled
          - refunded
          allOf:
          - $ref: '#/components/schemas/SponsoredTxState'
          description: Current lifecycle state of the sponsored transaction.
        txHash:
          type:
          - string
          - 'null'
          description: On-chain transaction hash for direct flows; null until known.
        confirmations:
          type: integer
          description: Number of on-chain confirmations observed for TxHash.
          format: int64
        error:
          allOf:
          - $ref: '#/components/schemas/SponsoredTxError'
          description: Failure details when State is Org.Front.Core.Contracts.GasSponsorship.SponsoredTxState.Failed.
        originTxHashes:
          type:
          - array
          - 'null'
          items:
            type: string
          description: "Origin-chain transaction hashes for routed flows (bridge/swap)\n            — populated from Relay's `inTxHashes`. Empty for `Direct` transfers, which keep\n            using TxHash."
        destinationTxHashes:
          type:
          - array
          - 'null'
          items:
            type: string
          description: "Destination-chain transaction hashes for routed flows —\n            populated from Relay's `txHashes`. Empty until Relay reports the destination fill."
      additionalProperties: false
      description: 'Output of `IRelaySponsorshipStrategy.GetStatusAsync`. Returned via

        `GET /v1/sponsorship/{trackingId}`.'
    SubmitStatus:
      enum:
      - unknown
      - submitted
      - alreadySubmitted
      type: string
      description: Result of broadcasting a sponsored transaction. Numeric values are part of the wire contract.
    SubmitSponsoredTxResponse:
      type: object
      properties:
        status:
          enum:
          - unknown
          - submitted
          - alreadySubmitted
          allOf:
          - $ref: '#/components/schemas/SubmitStatus'
          description: "Terminal status: Org.Front.Core.Contracts.GasSponsorship.SubmitStatus.Submitted on first success,\n            Org.Front.Core.Contracts.GasSponsorship.SubmitStatus.AlreadySubmitted when the same tracking id has already been\n            broadcast (idempotent replay)."
        txHash:
          type:
          - string
          - 'null'
          description: "On-chain transaction hash; present once broadcast succeeded. Nullable\n            to allow the idempotent Org.Front.Core.Contracts.GasSponsorship.SubmitStatus.AlreadySubmitted replay path to return a\n            minimal response when the persisted hash is not in the request scope."
      additionalProperties: false
      description: 'Output of `IRelaySponsorshipStrategy.SubmitAsync`. Returned via

        `POST /v1/sponsorship/submit`.'
    BuildSponsoredTxResponse:
      type: object
      properties:
        trackingId:
          type: string
          description: "Server-issued id correlating subsequent\n            `/submit` and `/status` calls back to a ledger entry. Surface this to clients."
          format: uuid
        strategy:
          enum:
          - unknown
          - metaMaskGasIncluded
          - alchemySolanaFeePayer
          - relayLinkEvmFeeSponsor
          allOf:
          - $ref: '#/components/schemas/GasSponsorshipStrategyKind'
          description: The strategy that built the payload.
        payload:
          allOf:
          - $ref: '#/components/schemas/SponsoredTxPayload'
          description: "Strategy-specific payload the client must sign and return on\n            `/submit`. For Alchemy on Solana this is a base64-encoded V0 transaction with slot 0\n            already signed by Alchemy and slot 1 awaiting the user's signature."
        additionalPayloads:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/SponsoredTxPayload'
          description: "Additional payloads the client must sign in order when the\n            route requires multiple signatures (e.g., Permit2 + ERC-3009 authorize1). The FE prompts the\n            wallet for Payload first, then each entry here in order, then submits all\n            signatures together on `/submit` alongside `AdditionalSignedPayloads`. Null/empty\n            for routes that need a single signature (today: every direct ERC-3009 transfer and most\n            USDC same-chain swaps)."
      additionalProperties: false
      description: 'Output of `IRelaySponsorshipStrategy.BuildAsync`. Returned to the caller via the

        `POST /v1/sponsorship/build` response.'
    SponsoredTxError:
      type: object
      properties:
        code:
          type:
          - string
          - 'null'
        message:
          type:
          - string
          - 'null'
      additionalProperties: false
      description: Error envelope attached to Org.Front.Core.Contracts.GasSponsorship.SponsoredTxStatus when the transaction failed.
    ApiResultStatus:
      enum:
      - ok
      - serverFailure
      - permissionDenied
      - badRequest
      - notFound
      - conflict
      - tooManyRequest
      - locked
      - unavailableForLegalReasons
      type: string
    GasSponsorshipStrategyKind:
      enum:
      - unknown
      - metaMaskGasIncluded
      - alchemySolanaFeePayer
      - relayLinkEvmFeeSponsor
      type: string
      description: 'Identifies a concrete gas sponsorship strategy. Used as the keyed-services DI key for

        `IGasSponsorshipStrategy` registrations, persisted on

        `ClientGasSponsorshipPolicy.StrategyOrder`'
    SubmitSponsorshipRequestBody:
      type: object
      properties:
        trackingId:
          type: string
          format: uuid
        signedPayload:
          allOf:
          - $ref: '#/components/schemas/SubmitSponsorshipSignedPayload'
        additionalSignedPayloads:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/SubmitSponsorshipSignedPayload'
          description: 'Additional client-signed payloads (in signing order) for routes that returned multiple

            payloads at `/build` time (e.g., Permit2 + ERC-3009 authorize1). Null/empty for

            single-signature routes.'
      additionalProperties: false
    SponsoredTxPayload:
      type: object
      properties:
        payloadType:
          type:
          - string
          - 'null'
          description: Wire-stable discriminator (e.g., `solana-v0-tx`).
        payloadBase64:
          type:
          - string
          - 'null'
          description: Base64-encoded serialized payload.
        slotsRemainingToSign:
          type:
          - array
          - 'null'
          items:
            type: integer
            format: int32
          description: "For multi-sig payloads, the signature slots the client\n            still owes. For Alchemy on Solana this is `[1]` (user signs slot 1; Alchemy already\n            signed slot 0). Empty for payloads that need no client signature."
      additionalProperties: false
      description: Strategy-specific payload returned by `/build` for the client to sign.
    SponsoredTxStatusApiResult:
      type: object
      properties:
        status:
          enum:
          - ok
          - serverFailure
          - permissionDenied
          - badRequest
          - notFound
          - conflict
          - tooManyRequest
          - locked
          - unavailableForLegalReasons
          allOf:
          - $ref: '#/components/schemas/ApiResultStatus'
          readOnly: true
        message:
          type:
          - string
          - 'null'
          description: A message generated by the API
        displayMessage:
          type:
          - string
          - 'null'
          description: User-friendly display message that can be presented to the end user
        errorHash:
          type:
          - string
          - 'null'
          description: An error grouping hash from string components and caller information. Used by bugsnag on FE for correct error grouping
          readOnly: true
        teamCode:
          type:
          - string
          - 'null'
          description: 'Opaque team code for error routing. Resolved from exception origin or caller file path via CODEOWNERS.

            Format: 2-character code (e.g., "7K", "M2"). Use for alerting/routing, not display.'
          readOnly: true
        errorType:
          type:
          - string
          - 'null'
          description: 'Strictly-typed error type that is explaining the reason of an unsuccessful status of the operation.

            All possible error types are available in the documentation.'
        errorData:
          readOnly: true
        content:
          allOf:
          - $ref: '#/components/schemas/SponsoredTxStatus'
          description: 'Output of `IRelaySponsorshipStrategy.GetStatusAsync`. Returned via

            `GET /v1/sponsorship/{trackingId}`.'
      additionalProperties: false
    BuildSponsoredTxResponseApiResult:
      type: object
      properties:
        status:
          enum:
          - ok
          - serverFailure
          - permissionDenied
          - badRequest
          - notFound
          - conflict
          - tooManyRequest
          - locked
          - unavailableForLegalReasons
          allOf:
          - $ref: '#/components/schemas/ApiResultStatus'
          readOnly: true
        message:
          type:
          - string
          - 'null'
          description: A message generated by the API
        displayMessage:
          type:
          - string
          - 'null'
          description: User-friendly display message that can be presented to the end user
        errorHash:
          type:
          - string
          - 'null'
          description: An error grouping hash from string components and caller information. Used by bugsnag on FE for correct error grouping
          readOnly: true
        teamCode:
          type:
          - string
          - 'null'
          description: 'Opaque team code for error routing. Resolved from exception origin or caller file path via CODEOWNERS.

            Format: 2-character code (e.g., "7K", "M2"). Use for alerting/routing, not display.'
          readOnly: true
        errorType:
          type:
          - string
          - 'null'
          description: 'Strictly-typed error type that is explaining the reason of an unsuccessful status of the operation.

            All possible error types are available in the documentation.'
        errorData:
          readOnly: true
        content:
          allOf:
          - $ref: '#/components/schemas/BuildSponsoredTxResponse'
          description: 'Output of `IRelaySponsorshipStrategy.BuildAsync`. Returned to the caller via the

            `POST /v1/sponsorship/build` response.'
      additionalProperties: false
    SponsoredTxState:
      enum:
      - unknown
      - built
      - submitted
      - confirmed
      - failed
      - cancelled
      - refunded
      type: string
      description: 'Lifecycle state of a `GasSponsorshipLedgerEntry`. Numeric values are part of the

        persistence + wire contract.'
    BuildSponsorshipRequestBody:
      type: object
      properties:
        transferPreviewId:
          type: string
          format: uuid
        fromAddress:
          type:
          - string
          - 'null'
      additionalProperties: false
    SubmitSponsorshipSignedPayload:
      type: object
      properties:
        payloadType:
          type:
          - string
          - 'null'
        signedPayloadBase64:
          type:
          - string
          - 'null'
      additionalProperties: false
    SubmitSponsoredTxResponseApiResult:
      type: object
      properties:
        status:
          enum:
          - ok
          - serverFailure
          - permissionDenied
          - badRequest
          - notFound
          - conflict
          - tooManyRequest
          - locked
          - unavailableForLegalReasons
          allOf:
          - $ref: '#/components/schemas/ApiResultStatus'
          readOnly: true
        message:
          type:
          - string
          - 'null'
          description: A message generated by the API
        displayMessage:
          type:
          - string
          - 'null'
          description: User-friendly display message that can be presented to the end user
        errorHash:
          type:
          - string
          - 'null'
          description: An error grouping hash from string components and caller information. Used by bugsnag on FE for correct error grouping
          readOnly: true
        teamCode:
          type:
          - string
          - 'null'
          description: 'Opaque team code for error routing. Resolved from exception origin or caller file path via CODEOWNERS.

            Format: 2-character code (e.g., "7K", "M2"). Use for alerting/routing, not display.'
          readOnly: true
        errorType:
          type:
          - string
          - 'null'
          description: 'Strictly-typed error type that is explaining the reason of an unsuccessful status of the operation.

            All possible error types are available in the documentation.'
        errorData:
          readOnly: true
        content:
          allOf:
          - $ref: '#/components/schemas/SubmitSponsoredTxResponse'
          description: 'Output of `IRelaySponsorshipStrategy.SubmitAsync`. Returned via

            `POST /v1/sponsorship/submit`.'
      additionalProperties: false
  securitySchemes:
    Client-Secret:
      type: apiKey
      description: Contact Mesh to get client Secret
      name: X-Client-Secret
      in: header
    Client-Id:
      type: apiKey
      description: Contact Mesh to get client Id
      name: X-Client-Id
      in: header