Create an account

You must complete the Know Your Customer (KYC) process before creating a customer account.

To create a customer account, use the Create an account endpoint. Each request requires a customer id and your Api Key:

curl --request POST \
     --url https://api.gravv.xyz/v1/accounts \
     --header 'Api-Key: <API_KEY>' \
     --header 'Idempotency-Key: 979879887678789_attempt_1' \
     --header 'content-type: application/json' \
     --data '
{
  "currency": "USD",
  "type": "regular",
  "blockchain_network": "polygon",
  "label": "Jane Doe",
  "customer_id": "<customer id>"
}
'

After sending the request, you will get a response that includes the account id, a wallet address, and virtual account details:

{
  "data": {
    "assets": [
      {
        "balance": "0",
        "decimals": 0,
        "symbol": "USDC"
      }
    ],
    "balance": "0.00",
    "blockchain_network": "polygon",
    "capabilities": [
      "transfer",
      "receive",
      "remittance"
    ],
    "currency": "USD",
    "customer_id": "d12ded01-9081-4a3c-a76c-70654f0a0175",
    "date_created": "2025-10-07T09:49:23Z",
    "id": "a4d83e55-435e-41c9-9a0b-dcb99f690c95",
    "label": "Jane Doe",
    "status": "active",
    "tenant_id": "cd90c45c-fa78-4624-a80a-642be301c812",
    "tenant_name": "Dahmoh",
    "tier": "",
    "type": "regular",
    "virtual_account_bank_account_number": "900300758080",
    "virtual_account_bank_address": "1800 North Pole St., Orlando, FL 32801",
    "virtual_account_bank_beneficiary_address": "1206 BEAR CREEK RD APT 1100, Hung, NJ 12345, US",
    "virtual_account_bank_name": "Bank of Nowhere",
    "virtual_account_bank_routing_number": "101019644",
    "virtual_account_id": "73cea894-bca7-43e2-b278-02bd6d991e2e",
    "wallet_address": "0xf73bdd069dc31aa8f334b177b175936ba98237a2"
  },
  "error": null
}

Account activation

A new account may return with a status of pending or active. 

If the account has a status of active right away, then you can use it immediately. A pending status means Gravv is still setting up the account's wallet and virtual account. You can't use an account that returns a status of pending for transactions yet.

When setup finishes, the status changes to active, and Gravv sends a webhook with the account.activated event type. For more information on the webhook event sent for an account, see Account events.

Wait for the account.activated webhook event before using the account. Alternatively, retrieve the account details until the status changes to active. For more information about retrieving account details, see Retrieve accounts.

Selecting a blockchain network

When creating accounts, you must choose a blockchain network to back each main account and customer account. For information on the supported blockchain networks and the stablecoins they accept, see Pay-in methods.