diff --git a/.stainless/stainless.yml b/.stainless/stainless.yml index bb7df08b..37082310 100644 --- a/.stainless/stainless.yml +++ b/.stainless/stainless.yml @@ -730,6 +730,7 @@ openapi: - "$.components.schemas.PaymentPolygonWalletInfo.allOf[0]" - "$.components.schemas.PaymentBaseWalletInfo.allOf[0]" - "$.components.schemas.PaymentEthereumWalletInfo.allOf[0]" + - "$.components.schemas.PaymentEmbeddedWalletInfo.allOf[0]" keys: [ "$ref" ] # ── Remove $ref to BaseExternalAccountInfo from external account variants ── diff --git a/mintlify/openapi.yaml b/mintlify/openapi.yaml index 29a960a4..f8489079 100644 --- a/mintlify/openapi.yaml +++ b/mintlify/openapi.yaml @@ -2491,6 +2491,12 @@ paths: This endpoint can only be used for quotes with a `source` which is either an internal account, or has direct pull functionality (e.g. ACH pull with an external account). + When the quote's `source` is an internal account of type `EMBEDDED_WALLET`, + the request must include a `Grid-Wallet-Signature` header. The signature is + produced by signing the `payloadToSign` value from the quote's + `paymentInstructions[].accountOrWalletInfo` entry with the session private + key of a verified authentication credential on the source Embedded Wallet. + Once executed, the quote cannot be cancelled and the transfer will be processed. operationId: executeQuote tags: @@ -2513,6 +2519,13 @@ paths: schema: type: string example: + - name: Grid-Wallet-Signature + in: header + required: false + description: Signature over the `payloadToSign` returned in the quote's `paymentInstructions[].accountOrWalletInfo` entry, produced with the session private key of a verified authentication credential on the source Embedded Wallet and base64-encoded. Required when the quote's source is an internal account of type `EMBEDDED_WALLET`; ignored for other source types. + schema: + type: string + example: MEUCIQDx7k2N0aK4p8f3vR9J6yT5wL1mB0sXnG2hQ4vJ8zYkCgIgZ4rP9dT7eWfU3oM6KjR1qSpNvBwL0tXyA2iG8fH5dE= responses: '200': description: | @@ -2529,7 +2542,7 @@ paths: schema: $ref: '#/components/schemas/Error400' '401': - description: Unauthorized + description: Unauthorized. Also returned when the quote's source is an internal account of type `EMBEDDED_WALLET` and the provided `Grid-Wallet-Signature` header is missing, malformed, or does not match the quote's `payloadToSign`. content: application/json: schema: @@ -6018,6 +6031,7 @@ components: - POLYGON_WALLET - BASE_WALLET - ETHEREUM_WALLET + - EMBEDDED_WALLET description: Type of payment account or wallet example: USD_ACCOUNT BasePaymentAccountInfo: @@ -7985,6 +7999,24 @@ components: type: string description: Unique reference code that must be included with the payment to properly credit it example: UMA-Q12345-REF + PaymentEmbeddedWalletInfo: + title: Embedded Wallet + allOf: + - $ref: '#/components/schemas/BasePaymentAccountInfo' + - type: object + required: + - accountType + - payloadToSign + properties: + accountType: + type: string + enum: + - EMBEDDED_WALLET + description: Discriminator value identifying this as Embedded Wallet payment instructions. + payloadToSign: + type: string + description: JSON-encoded transaction signing payload that must be signed, as-is (byte-for-byte, without re-serialization), with the session private key of a verified authentication credential on the source Embedded Wallet. The resulting signature is base64-encoded and passed as the `Grid-Wallet-Signature` header on `POST /quotes/{quoteId}/execute` to authorize the outbound transfer from the wallet. + example: '{"type":"ACTIVITY_TYPE_SIGN_TRANSACTION_V2","timestampMs":"1746736509954","organizationId":"org_abc123","parameters":{"signWith":"wallet_abc123def456","unsignedTransaction":"ea69b4bf05f775209f26ff0a34a05569180f7936579d5c4af9377ae550194f72","type":"TRANSACTION_TYPE_ETHEREUM"},"generateAppProofs":true}' PaymentInstructions: type: object required: @@ -8043,6 +8075,7 @@ components: - $ref: '#/components/schemas/PaymentPolygonWalletInfo' - $ref: '#/components/schemas/PaymentBaseWalletInfo' - $ref: '#/components/schemas/PaymentEthereumWalletInfo' + - $ref: '#/components/schemas/PaymentEmbeddedWalletInfo' discriminator: propertyName: accountType mapping: @@ -8089,6 +8122,7 @@ components: HTG_ACCOUNT: '#/components/schemas/PaymentHtgAccountInfo' JMD_ACCOUNT: '#/components/schemas/PaymentJmdAccountInfo' PKR_ACCOUNT: '#/components/schemas/PaymentPkrAccountInfo' + EMBEDDED_WALLET: '#/components/schemas/PaymentEmbeddedWalletInfo' InternalAccount: type: object required: @@ -12652,6 +12686,7 @@ components: description: |- Whether to immediately execute the quote after creation. If true, the quote will be executed and the transaction will be created at the current exchange rate. It should only be used if you don't want to lock and view rate details before executing the quote. If you are executing a pre-existing quote, use the `/quotes/{quoteId}/execute` endpoint instead. This is false by default. This can only be used for quotes with a `source` which is either an internal account, or has direct pull functionality (e.g. ACH pull with an external account). + Not supported when the `source` is an internal account of type `EMBEDDED_WALLET`: those transfers require a `Grid-Wallet-Signature` over the `payloadToSign` returned in the quote response, which is not available in a combined create-and-execute call. Create the quote first with `immediatelyExecute: false` and then call `POST /quotes/{quoteId}/execute` with the signature header. example: false description: type: string diff --git a/openapi.yaml b/openapi.yaml index 29a960a4..f8489079 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -2491,6 +2491,12 @@ paths: This endpoint can only be used for quotes with a `source` which is either an internal account, or has direct pull functionality (e.g. ACH pull with an external account). + When the quote's `source` is an internal account of type `EMBEDDED_WALLET`, + the request must include a `Grid-Wallet-Signature` header. The signature is + produced by signing the `payloadToSign` value from the quote's + `paymentInstructions[].accountOrWalletInfo` entry with the session private + key of a verified authentication credential on the source Embedded Wallet. + Once executed, the quote cannot be cancelled and the transfer will be processed. operationId: executeQuote tags: @@ -2513,6 +2519,13 @@ paths: schema: type: string example: + - name: Grid-Wallet-Signature + in: header + required: false + description: Signature over the `payloadToSign` returned in the quote's `paymentInstructions[].accountOrWalletInfo` entry, produced with the session private key of a verified authentication credential on the source Embedded Wallet and base64-encoded. Required when the quote's source is an internal account of type `EMBEDDED_WALLET`; ignored for other source types. + schema: + type: string + example: MEUCIQDx7k2N0aK4p8f3vR9J6yT5wL1mB0sXnG2hQ4vJ8zYkCgIgZ4rP9dT7eWfU3oM6KjR1qSpNvBwL0tXyA2iG8fH5dE= responses: '200': description: | @@ -2529,7 +2542,7 @@ paths: schema: $ref: '#/components/schemas/Error400' '401': - description: Unauthorized + description: Unauthorized. Also returned when the quote's source is an internal account of type `EMBEDDED_WALLET` and the provided `Grid-Wallet-Signature` header is missing, malformed, or does not match the quote's `payloadToSign`. content: application/json: schema: @@ -6018,6 +6031,7 @@ components: - POLYGON_WALLET - BASE_WALLET - ETHEREUM_WALLET + - EMBEDDED_WALLET description: Type of payment account or wallet example: USD_ACCOUNT BasePaymentAccountInfo: @@ -7985,6 +7999,24 @@ components: type: string description: Unique reference code that must be included with the payment to properly credit it example: UMA-Q12345-REF + PaymentEmbeddedWalletInfo: + title: Embedded Wallet + allOf: + - $ref: '#/components/schemas/BasePaymentAccountInfo' + - type: object + required: + - accountType + - payloadToSign + properties: + accountType: + type: string + enum: + - EMBEDDED_WALLET + description: Discriminator value identifying this as Embedded Wallet payment instructions. + payloadToSign: + type: string + description: JSON-encoded transaction signing payload that must be signed, as-is (byte-for-byte, without re-serialization), with the session private key of a verified authentication credential on the source Embedded Wallet. The resulting signature is base64-encoded and passed as the `Grid-Wallet-Signature` header on `POST /quotes/{quoteId}/execute` to authorize the outbound transfer from the wallet. + example: '{"type":"ACTIVITY_TYPE_SIGN_TRANSACTION_V2","timestampMs":"1746736509954","organizationId":"org_abc123","parameters":{"signWith":"wallet_abc123def456","unsignedTransaction":"ea69b4bf05f775209f26ff0a34a05569180f7936579d5c4af9377ae550194f72","type":"TRANSACTION_TYPE_ETHEREUM"},"generateAppProofs":true}' PaymentInstructions: type: object required: @@ -8043,6 +8075,7 @@ components: - $ref: '#/components/schemas/PaymentPolygonWalletInfo' - $ref: '#/components/schemas/PaymentBaseWalletInfo' - $ref: '#/components/schemas/PaymentEthereumWalletInfo' + - $ref: '#/components/schemas/PaymentEmbeddedWalletInfo' discriminator: propertyName: accountType mapping: @@ -8089,6 +8122,7 @@ components: HTG_ACCOUNT: '#/components/schemas/PaymentHtgAccountInfo' JMD_ACCOUNT: '#/components/schemas/PaymentJmdAccountInfo' PKR_ACCOUNT: '#/components/schemas/PaymentPkrAccountInfo' + EMBEDDED_WALLET: '#/components/schemas/PaymentEmbeddedWalletInfo' InternalAccount: type: object required: @@ -12652,6 +12686,7 @@ components: description: |- Whether to immediately execute the quote after creation. If true, the quote will be executed and the transaction will be created at the current exchange rate. It should only be used if you don't want to lock and view rate details before executing the quote. If you are executing a pre-existing quote, use the `/quotes/{quoteId}/execute` endpoint instead. This is false by default. This can only be used for quotes with a `source` which is either an internal account, or has direct pull functionality (e.g. ACH pull with an external account). + Not supported when the `source` is an internal account of type `EMBEDDED_WALLET`: those transfers require a `Grid-Wallet-Signature` over the `payloadToSign` returned in the quote response, which is not available in a combined create-and-execute call. Create the quote first with `immediatelyExecute: false` and then call `POST /quotes/{quoteId}/execute` with the signature header. example: false description: type: string diff --git a/openapi/components/schemas/common/PaymentAccountType.yaml b/openapi/components/schemas/common/PaymentAccountType.yaml index 6a2dbb36..30ff1bc1 100644 --- a/openapi/components/schemas/common/PaymentAccountType.yaml +++ b/openapi/components/schemas/common/PaymentAccountType.yaml @@ -25,5 +25,6 @@ enum: - POLYGON_WALLET - BASE_WALLET - ETHEREUM_WALLET + - EMBEDDED_WALLET description: Type of payment account or wallet example: USD_ACCOUNT diff --git a/openapi/components/schemas/common/PaymentEmbeddedWalletInfo.yaml b/openapi/components/schemas/common/PaymentEmbeddedWalletInfo.yaml new file mode 100644 index 00000000..d91fd070 --- /dev/null +++ b/openapi/components/schemas/common/PaymentEmbeddedWalletInfo.yaml @@ -0,0 +1,23 @@ +title: Embedded Wallet +allOf: + - $ref: ./BasePaymentAccountInfo.yaml + - type: object + required: + - accountType + - payloadToSign + properties: + accountType: + type: string + enum: + - EMBEDDED_WALLET + description: Discriminator value identifying this as Embedded Wallet payment instructions. + payloadToSign: + type: string + description: >- + JSON-encoded transaction signing payload that must be signed, as-is + (byte-for-byte, without re-serialization), with the session private + key of a verified authentication credential on the source Embedded + Wallet. The resulting signature is base64-encoded and passed as the + `Grid-Wallet-Signature` header on `POST /quotes/{quoteId}/execute` + to authorize the outbound transfer from the wallet. + example: '{"type":"ACTIVITY_TYPE_SIGN_TRANSACTION_V2","timestampMs":"1746736509954","organizationId":"org_abc123","parameters":{"signWith":"wallet_abc123def456","unsignedTransaction":"ea69b4bf05f775209f26ff0a34a05569180f7936579d5c4af9377ae550194f72","type":"TRANSACTION_TYPE_ETHEREUM"},"generateAppProofs":true}' diff --git a/openapi/components/schemas/common/PaymentInstructions.yaml b/openapi/components/schemas/common/PaymentInstructions.yaml index a01bbd52..c8037cff 100644 --- a/openapi/components/schemas/common/PaymentInstructions.yaml +++ b/openapi/components/schemas/common/PaymentInstructions.yaml @@ -57,6 +57,7 @@ properties: - $ref: ../common/PaymentPolygonWalletInfo.yaml - $ref: ../common/PaymentBaseWalletInfo.yaml - $ref: ../common/PaymentEthereumWalletInfo.yaml + - $ref: ../common/PaymentEmbeddedWalletInfo.yaml discriminator: propertyName: accountType mapping: @@ -103,3 +104,4 @@ properties: HTG_ACCOUNT: ../common/PaymentHtgAccountInfo.yaml JMD_ACCOUNT: ../common/PaymentJmdAccountInfo.yaml PKR_ACCOUNT: ../common/PaymentPkrAccountInfo.yaml + EMBEDDED_WALLET: ../common/PaymentEmbeddedWalletInfo.yaml diff --git a/openapi/components/schemas/quotes/QuoteRequest.yaml b/openapi/components/schemas/quotes/QuoteRequest.yaml index e26b003a..5b5cb20a 100644 --- a/openapi/components/schemas/quotes/QuoteRequest.yaml +++ b/openapi/components/schemas/quotes/QuoteRequest.yaml @@ -42,6 +42,13 @@ properties: This can only be used for quotes with a `source` which is either an internal account, or has direct pull functionality (e.g. ACH pull with an external account). + + Not supported when the `source` is an internal account of type + `EMBEDDED_WALLET`: those transfers require a `Grid-Wallet-Signature` + over the `payloadToSign` returned in the quote response, which is not + available in a combined create-and-execute call. Create the quote + first with `immediatelyExecute: false` and then call + `POST /quotes/{quoteId}/execute` with the signature header. example: false description: type: string diff --git a/openapi/paths/quotes/quotes_{quoteId}_execute.yaml b/openapi/paths/quotes/quotes_{quoteId}_execute.yaml index 348a6149..f7020d0a 100644 --- a/openapi/paths/quotes/quotes_{quoteId}_execute.yaml +++ b/openapi/paths/quotes/quotes_{quoteId}_execute.yaml @@ -7,6 +7,12 @@ post: This endpoint can only be used for quotes with a `source` which is either an internal account, or has direct pull functionality (e.g. ACH pull with an external account). + When the quote's `source` is an internal account of type `EMBEDDED_WALLET`, + the request must include a `Grid-Wallet-Signature` header. The signature is + produced by signing the `payloadToSign` value from the quote's + `paymentInstructions[].accountOrWalletInfo` entry with the session private + key of a verified authentication credential on the source Embedded Wallet. + Once executed, the quote cannot be cancelled and the transfer will be processed. operationId: executeQuote tags: @@ -30,6 +36,19 @@ post: schema: type: string example: + - name: Grid-Wallet-Signature + in: header + required: false + description: >- + Signature over the `payloadToSign` returned in the quote's + `paymentInstructions[].accountOrWalletInfo` entry, produced with the + session private key of a verified authentication credential on the + source Embedded Wallet and base64-encoded. Required when the quote's + source is an internal account of type `EMBEDDED_WALLET`; ignored for + other source types. + schema: + type: string + example: MEUCIQDx7k2N0aK4p8f3vR9J6yT5wL1mB0sXnG2hQ4vJ8zYkCgIgZ4rP9dT7eWfU3oM6KjR1qSpNvBwL0tXyA2iG8fH5dE= responses: '200': description: > @@ -47,7 +66,11 @@ post: schema: $ref: ../../components/schemas/errors/Error400.yaml '401': - description: Unauthorized + description: >- + Unauthorized. Also returned when the quote's source is an internal + account of type `EMBEDDED_WALLET` and the provided + `Grid-Wallet-Signature` header is missing, malformed, or does not + match the quote's `payloadToSign`. content: application/json: schema: @@ -70,5 +93,3 @@ post: application/json: schema: $ref: ../../components/schemas/errors/Error500.yaml - -