API Reference

Transfers overview

Use the Transfers API to move funds, attach supporting documents, resume a paused transfer, and read the currency pairs, countries, address forms and indicative rates that transfers use.

Create a transfer or browse the operations in this category.

Choose a transfer flow and build it.

How it works

A single endpoint, POST /v1/transfer, moves funds between internal accounts, external accounts (payees) and crypto wallets. The response is HTTP 200 with one of these transfer_status values:

pending: Gravv accepted the transfer and is processing it in the background. Follow it with webhooks or GET /v1/transactions/{transaction_id}.
paused: Gravv accepted the transfer, but it needs something from you first, such as a supporting document, the sender's details or a decision on a limit. requirements lists what it needs, and expires_at is the deadline to resume it. Resume it with POST /v1/transfer/{id}/resume. See Paused transfers.

Flow	Destination	Guide
Internal	Another account your customer holds at Gravv	Internal transfers
US bank rails	A US external account, by ACH, wire or RTP	External transfers
International	A SWIFT, SEPA, Faster Payments or local payee	International transfers
Crypto	A blockchain wallet, on the same or another network, or a conversion	Crypto transfers

A listed country or pair is not an open route. The rates, currency and country endpoints describe the tables Gravv uses to price and address transfers. They do not show whether a payout route is open for your business. Gravv decides that when you send the transfer, and a closed route returns transfers to XX/CCC are not available at this time. See what is open today on Payments and supported countries.

Endpoints

Endpoint	Description
`POST /v1/transfer`	Create a transfer between internal accounts, external accounts or crypto wallets
`POST /v1/transfer/documents`	Upload a supporting document to pass in `supporting_document_ids`. The file is PDF, PNG or JPEG, at most 700 KB, and under 500 KB in sandbox
`POST /v1/transfer/{id}/resume`	Resume a paused transfer with what its `requirements` asked for
`GET /v1/transfer/rates`	Get indicative rates for a payout currency, or a priced preview of a USDT and USDC conversion. The rate is not locked
`GET /v1/transfer/supported-currencies`	List the currency pairs transfers can be priced in
`GET /v1/transfer/supported-countries`	List the countries a payee can be in, with ISO codes and local currency
`GET /v1/transfer/supported-countries-for-address`	List the countries for addresses, with `states` where they apply

Authentication

All requests use https://api.gravv.xyz and authenticate with the Api-Key header. Every POST needs its own new Idempotency-Key, including each resume attempt. See Idempotent requests. Most errors return HTTP 400 with the reason in error. Only some also carry a code, so match on the message.

Was this page helpful?