[brale-link] Add stablecoin provider account API surface#594
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub. 2 Skipped Deployments
|
✱ Stainless preview builds for gridThis PR will update the cli csharp go kotlin openapi php python ruby typescript ✅ grid-ruby studio · code
|
Greptile SummaryAdds the Grid API surface for Brale-link stablecoin provider accounts: three new endpoints (link, list, get), five new schema files, and new 400/404 error codes. The bundled
Confidence Score: 4/5Safe to merge; all three new endpoints follow established patterns, credentials are write-only, and the bundled files are up to date. The spec is internally consistent and the generated bundles match the source. Two minor documentation gaps and the absence of a dedicated error code to distinguish a bad apiClientSecret from a malformed request are the only items worth addressing before the next public-facing release. openapi/paths/stablecoins/stablecoin-provider-accounts.yaml and openapi/components/schemas/stablecoins/StablecoinProviderAccountListResponse.yaml have the small gaps noted in the review comments.
|
| Filename | Overview |
|---|---|
| openapi/components/schemas/stablecoins/StablecoinProviderAccount.yaml | New schema for the provider account link resource; required fields and types look correct, lastVerifiedAt is correctly optional. |
| openapi/components/schemas/stablecoins/StablecoinProviderAccountListResponse.yaml | Pagination response schema; nextCursor description is missing the "(only present if hasMore is true)" note found in every other list response schema in the repo. |
| openapi/paths/stablecoins/stablecoin-provider-accounts.yaml | Defines POST (link) and GET (list) for provider accounts; provider/status query params lack descriptions; no dedicated error code for provider credential verification failure at link time. |
| openapi/paths/stablecoins/stablecoin-provider-accounts_{stablecoinProviderAccountId}.yaml | Defines GET by ID for provider account links; correct 404 / 401 / 500 responses, no issues found. |
| openapi/components/schemas/errors/Error400.yaml | Adds three new 400 error codes for stablecoin provider account state errors; enum and description table entries are in sync. |
| openapi/components/schemas/errors/Error404.yaml | Adds STABLECOIN_PROVIDER_ACCOUNT_NOT_FOUND to the 404 enum; table and enum are consistent. |
| openapi/components/schemas/stablecoins/StablecoinProviderAccountLinkRequest.yaml | Link request schema; apiClientSecret is correctly marked writeOnly: true; optional providerAccountId is well-described. |
| openapi/openapi.yaml | Registers the two new stablecoin provider account path files and adds the Stablecoins tag; references look correct. |
Sequence Diagram
%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
participant Client
participant GridAPI
participant BraleProvider
Client->>GridAPI: POST /stablecoin-provider-accounts
GridAPI->>BraleProvider: Verify credentials
BraleProvider-->>GridAPI: Account verified (providerAccountId)
GridAPI-->>Client: 201 StablecoinProviderAccount (ACTIVE)
Client->>GridAPI: GET /stablecoin-provider-accounts
GridAPI-->>Client: 200 StablecoinProviderAccountListResponse
Client->>GridAPI: "GET /stablecoin-provider-accounts/{id}"
GridAPI-->>Client: 200 StablecoinProviderAccount
%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
participant Client
participant GridAPI
participant BraleProvider
Client->>GridAPI: POST /stablecoin-provider-accounts
GridAPI->>BraleProvider: Verify credentials
BraleProvider-->>GridAPI: Account verified (providerAccountId)
GridAPI-->>Client: 201 StablecoinProviderAccount (ACTIVE)
Client->>GridAPI: GET /stablecoin-provider-accounts
GridAPI-->>Client: 200 StablecoinProviderAccountListResponse
Client->>GridAPI: "GET /stablecoin-provider-accounts/{id}"
GridAPI-->>Client: 200 StablecoinProviderAccount
Prompt To Fix All With AI
Fix the following 3 code review issues. Work through them one at a time, proposing concise fixes.
---
### Issue 1 of 3
openapi/components/schemas/stablecoins/StablecoinProviderAccountListResponse.yaml:13-15
**`nextCursor` description omits when-present condition**
Every other list response in the codebase (`CustomerListResponse`, `TransactionListResponse`, etc.) documents `nextCursor` as "Cursor to retrieve the next page of results (only present if `hasMore` is true)". Without that note, clients have no contract guarantee about when the field is populated and may attempt to paginate even when `hasMore` is `false`.
```suggestion
nextCursor:
type: string
description: Cursor to retrieve the next page of results (only present if hasMore is true).
```
### Issue 2 of 3
openapi/paths/stablecoins/stablecoin-provider-accounts.yaml:60-68
**`provider` and `status` query params lack `description` fields**
The `limit` and `cursor` parameters on this same endpoint each carry a `description`, but `provider` and `status` do not. All query parameters on other list endpoints include descriptions (e.g., `GET /customers`). Without them, generated docs and SDK clients surface these params with no context about their purpose or effect on the result set.
### Issue 3 of 3
openapi/paths/stablecoins/stablecoin-provider-accounts.yaml:34-52
**No error code for failed provider credential verification**
The three new 400 codes (`STABLECOIN_PROVIDER_ACCOUNT_INVALID`, `STABLECOIN_PROVIDER_ACCOUNT_REVOKED`, `STABLECOIN_PROVIDER_ACCOUNT_SELECTION_REQUIRED`) address post-link state errors, but there is no code to signal that the submitted `apiClientSecret` itself failed provider-side verification during the link call. A caller whose credentials are outright rejected would receive a generic `INVALID_INPUT` 400, making it impossible to distinguish a bad secret from a bad payload. A dedicated code (e.g., `STABLECOIN_PROVIDER_CREDENTIALS_INVALID`) would close this gap.
Reviews (1): Last reviewed commit: "Add stablecoin provider account API surf..." | Re-trigger Greptile
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| nextCursor: | ||
| type: string | ||
| description: Cursor to retrieve the next page of results. |
There was a problem hiding this comment.
nextCursor description omits when-present condition
Every other list response in the codebase (CustomerListResponse, TransactionListResponse, etc.) documents nextCursor as "Cursor to retrieve the next page of results (only present if hasMore is true)". Without that note, clients have no contract guarantee about when the field is populated and may attempt to paginate even when hasMore is false.
| nextCursor: | |
| type: string | |
| description: Cursor to retrieve the next page of results. | |
| nextCursor: | |
| type: string | |
| description: Cursor to retrieve the next page of results (only present if hasMore is true). |
Prompt To Fix With AI
This is a comment left during a code review.
Path: openapi/components/schemas/stablecoins/StablecoinProviderAccountListResponse.yaml
Line: 13-15
Comment:
**`nextCursor` description omits when-present condition**
Every other list response in the codebase (`CustomerListResponse`, `TransactionListResponse`, etc.) documents `nextCursor` as "Cursor to retrieve the next page of results (only present if `hasMore` is true)". Without that note, clients have no contract guarantee about when the field is populated and may attempt to paginate even when `hasMore` is `false`.
```suggestion
nextCursor:
type: string
description: Cursor to retrieve the next page of results (only present if hasMore is true).
```
How can I resolve this? If you propose a fix, please make it concise.Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
| tags: | ||
| - Stablecoins | ||
| security: | ||
| - BasicAuth: [] | ||
| parameters: | ||
| - name: provider | ||
| in: query | ||
| required: false | ||
| schema: |
There was a problem hiding this comment.
provider and status query params lack description fields
The limit and cursor parameters on this same endpoint each carry a description, but provider and status do not. All query parameters on other list endpoints include descriptions (e.g., GET /customers). Without them, generated docs and SDK clients surface these params with no context about their purpose or effect on the result set.
Prompt To Fix With AI
This is a comment left during a code review.
Path: openapi/paths/stablecoins/stablecoin-provider-accounts.yaml
Line: 60-68
Comment:
**`provider` and `status` query params lack `description` fields**
The `limit` and `cursor` parameters on this same endpoint each carry a `description`, but `provider` and `status` do not. All query parameters on other list endpoints include descriptions (e.g., `GET /customers`). Without them, generated docs and SDK clients surface these params with no context about their purpose or effect on the result set.
How can I resolve this? If you propose a fix, please make it concise.Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: ../../components/schemas/errors/Error400.yaml | ||
| '401': | ||
| description: Unauthorized | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: ../../components/schemas/errors/Error401.yaml | ||
| '409': | ||
| description: Conflict | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: ../../components/schemas/errors/Error409.yaml | ||
| '500': | ||
| description: Internal service error | ||
| content: |
There was a problem hiding this comment.
The three new 400 codes (STABLECOIN_PROVIDER_ACCOUNT_INVALID, STABLECOIN_PROVIDER_ACCOUNT_REVOKED, STABLECOIN_PROVIDER_ACCOUNT_SELECTION_REQUIRED) address post-link state errors, but there is no code to signal that the submitted apiClientSecret itself failed provider-side verification during the link call. A caller whose credentials are outright rejected would receive a generic INVALID_INPUT 400, making it impossible to distinguish a bad secret from a bad payload. A dedicated code (e.g., STABLECOIN_PROVIDER_CREDENTIALS_INVALID) would close this gap.
Prompt To Fix With AI
This is a comment left during a code review.
Path: openapi/paths/stablecoins/stablecoin-provider-accounts.yaml
Line: 34-52
Comment:
**No error code for failed provider credential verification**
The three new 400 codes (`STABLECOIN_PROVIDER_ACCOUNT_INVALID`, `STABLECOIN_PROVIDER_ACCOUNT_REVOKED`, `STABLECOIN_PROVIDER_ACCOUNT_SELECTION_REQUIRED`) address post-link state errors, but there is no code to signal that the submitted `apiClientSecret` itself failed provider-side verification during the link call. A caller whose credentials are outright rejected would receive a generic `INVALID_INPUT` 400, making it impossible to distinguish a bad secret from a bad payload. A dedicated code (e.g., `STABLECOIN_PROVIDER_CREDENTIALS_INVALID`) would close this gap.
How can I resolve this? If you propose a fix, please make it concise.
## Summary - Added `FAMILY_SUPPORT` and `SALARY_PAYMENT` to the documented purpose of payment codes in the cross-currency transfers guide These values were added to the OpenAPI schema in PR #592 (commit 460f14d) but the Mintlify documentation wasn't updated. ## Changes **Documentation (mintlify/):** - `mintlify/snippets/sending/cross-currency.mdx` - Added missing purpose of payment codes to match the schema ## Not updated (no changes needed) - **Contact verification endpoints** (PR #557): Already documented in `mintlify/snippets/kyc/kyc-unregulated.mdx` - **Stablecoin provider accounts** (PR #594): New API surface - not referenced in existing guides - **Kotlin sample app**: Uses SDK factory method for PurposeOfPayment which auto-supports new values - **Grid Visualizer**: Uses `'GIFT'` as example value which remains valid 🤖 Generated with [Claude Code](https://claude.com/claude-code)
2 participants
Adds the Grid API surface required by the first Brale-link webdev PR: stablecoin provider account link/list/get endpoints, provider account models, and provider-account error codes. Validation: - make build - make lint