Changelog and versions
How the Gravv API is versioned, the dated changes you need to act on, and the behaviors these docs used to describe wrongly.
This page lists the changes that need something from you: dated API changes, retired routes, and places where these docs used to describe behavior the API does not have. If you built on the old text, check the rows below against your integration.
Example. Your collection handler branches on onramp_status. The first entry below says those values change on or after 31 October 2026, when onramp_status takes the values that new_onramp_status carries today. You change the handler to read new_onramp_status when it is present and onramp_status when it is not, and it keeps working through the change.
How versions work
- The version is part of the path:
https://api.gravv.xyz/v1/…orhttps://api.gravv.xyz/v2/…. There is no version header to send. - Most routes exist only under
/v1./v2covers accounts and account applications. See Accounts.
Changes to act on
| When | Change | What to do |
|---|---|---|
| On or after 31 October 2026 | The values in a collection's onramp_status change, and Gravv renames two collection event types |
Read new_onramp_status when it is present and onramp_status when it is not, and accept both event names. See Status label change |
| 16 October 2026 | The v1 accounts API is no longer documented, except the three calls that open and read your card account | Use the v2 accounts API. See Accounts. For the card account, see Card account |
| 16 October 2026 | Gravv supports accounts and wallets on five networks: Stellar, Polygon, Ethereum, Avalanche and Solana. Gravv no longer lists Base or the other networks | Open new accounts and wallets on one of the five. See Pay-in methods |
| Now | Payment links are retired | Take card payments through Collections. See Payment links (retired) |
| Now | Gravv publishes the MCP server as @gravv-infra/mcp. Earlier releases were @gravvfi/mcp |
Install @gravv-infra/mcp. See Gravv MCP server |
Documentation corrections
These pages described behavior the API does not have. They now match the API.
| Area | The docs used to say | What the API does |
|---|---|---|
| Rate limits | 10 requests a minute | 600 requests a minute per business, with bursts of up to 50. See Rate limits |
| Errors | Every error is a 400 |
Status codes differ by route and cause. See Errors |
| Idempotency | One key could cover several creates | Send a new Idempotency-Key for each POST. See Idempotent requests |
| Uploads | Keep every file under 500 KB, in live too | Each upload route has its own live limit, from 700 KB to 10 MB. The 500 KB rule is for sandbox, which refuses requests from about 600 KB. See Upload sizes |
| v2 accounts | Wait for account.activated |
A v2 account sends applications.accounts.completed, not account.activated. See Track activation |
| Cards | Back cards with an ordinary account | One account of type card per business backs every card. See Set up your card account |
| Card status | Send only status |
Send limit with every status update. Leaving it out sets the daily limit to 0. See Manage card status |
| Card PIN | Set the PIN with PATCH |
It is a PUT. See Manage card PIN |
| FX | Spot trades, market and limit orders, and a second approval | An exchange is a quote followed by an OTC order. An order you place with an API key needs no approval. See Foreign exchange |
| Transactions export | Up to 50,000 rows | At most the 10 newest matching rows. See Pagination |
| Settlement instructions | 20 a page by default, up to 100 | 10 a page by default, with no maximum. See Pagination |
| Webhooks | Deduplicate on X-Event-ID, with fixed retry numbers |
Deduplicate on the body's event_id, and read max_retries on the event. See Webhooks |
| Networks and methods | Sui and Tron accounts, and mobile money collections | Only the networks, rails and methods each page labels Available work today |