Accounts overview

Use the Accounts API to submit and process account applications, create accounts, retrieve account details, and update account status.

Start with account applications or browse the operations in this category.

Understand the account lifecycle before integrating the endpoints.

How it works

Accounts are opened for a customer in one of two ways:

Direct creation — call POST /v1/accounts to open an internal account immediately. Recommended for sandbox and most integrations.
Application flow — for providers that require review, create an application, collect terms-of-service acceptance, then submit and process it. Once processed successfully, the account is created and returned by the account endpoints.

The typical application sequence is: create → (optionally validate) → accept TOS → submit → process — or combine the last two with submit-and-process.

For sandbox and testing integrations, use polygon as the blockchain_network when creating accounts or applications.

Endpoint	Description
`POST /v1/accounts/applications`	Create an account application for a customer
`GET /v1/accounts/applications`	List applications with filters and pagination
`GET /v1/accounts/applications/pending`	List applications awaiting action
`GET /v1/accounts/applications/{id}`	Retrieve a single application
`PUT /v1/accounts/applications/{id}`	Update a draft or rejected application
`DELETE /v1/accounts/applications/{id}`	Delete an application
`POST /v1/accounts/applications/{id}/submit`	Mark an application as submitted for provider processing
`POST /v1/accounts/applications/{id}/process`	Process a submitted application with the provider
`POST /v1/accounts/applications/{id}/submit-and-process`	Submit and process in a single call
`GET /v1/accounts/applications/{id}/history`	Audit log of an application's state changes
`POST /v1/accounts/applications/tos`	Record the applicant's terms-of-service acceptance
`POST /v1/accounts/applications/validate`	Validate an application payload against provider rules without saving

Endpoint	Description
`POST /v1/accounts`	Create an internal account for a customer
`GET /v1/accounts`	List internal accounts with filters and pagination
`GET /v1/accounts/{account_id}`	Retrieve a single account
`PATCH /v1/accounts/{account_id}/status`	Freeze, reactivate, or close an account

Status	Meaning
`active`	Account is open and can send and receive funds
`frozen`	Account is suspended — set `active` to reactivate it
`deleted`	Account is closed permanently. Requires a zero wallet balance, and can't be changed again

System-managed accounts can't have their status updated.

All requests use https://api.gravv.xyz/v1/ and authenticate with the Api-Key header. See Authentication for details.

Was this page helpful?