List and read accounts

List your accounts with GET /v2/accounts, read one with GET /v2/accounts/{id}, and give payers the right bank details.

API version: v2.

Use these calls to read one account, give payers its bank details, read its balances and list accounts.

A money example. Ada's USD account is active. You read it and show her client the bank name, beneficiary name, account number and routing number. The client sends 1,200.00 USD by ACH, and the next read shows the new balance.

Read one account

curl --request GET \
     --url https://api.gravv.xyz/v2/accounts/6f1c2a9e-3b1d-4f7a-9c62-0d8e4b7a5c11 \
     --header 'Api-Key: <API_KEY>'

{
  "data": {
    "id": "6f1c2a9e-3b1d-4f7a-9c62-0d8e4b7a5c11",
    "status": "active",
    "currency": "USD",
    "category": "sub_account",
    "wallet_address": "0x5a3e9b0c7d2f41e8a6b4c3d2e1f0a9b8c7d6e5f4",
    "blockchain_network": "polygon",
    "virtual_account_bank_name": "Example Bank NA",
    "virtual_account_bank_account_number": "9876543210",
    "virtual_account_bank_routing_number": "123456780",
    "virtual_account_bank_beneficiary_name": "Ada Okafor",
    "balance": "0",
    "balance_source": "wallet",
    "settlement_enabled": false,
    "application_id": "5e7a9c1b-2d4f-4a6b-8c0d-e1f2a3b4c5d6"
  },
  "error": null
}

Bank details to give the payer

Bank details exist only once the account is active.

Account	virtual_account_bank_account_number	virtual_account_bank_routing_number	Also show
USD	US account number	ABA routing number	virtual_account_bank_name, virtual_account_bank_address, virtual_account_bank_beneficiary_name, virtual_account_bank_beneficiary_address
EUR, wallet-backed	IBAN	BIC	bank name, beneficiary name
GBP, wallet-backed	UK account number	sort code	bank name, beneficiary name
EUR or GBP, fiat-only (one IBAN)	the full IBAN	sort code	virtual_account_bank_metadata.bic. For a UK Faster Payment, the 8-digit account number is the last 8 characters of the IBAN
NGN	10-digit account number	empty	bank name, beneficiary name
KES	account number	empty	bank name
Any wallet-backed account			wallet_address and blockchain_network. The payer must send only USDC on that network

• bank_name and bank_code say which option holds the account. virtual_account_bank_name is the bank the payer names. The two can differ.
• A fiat-only USD account for a US resident has no virtual_account_bank_name or virtual_account_bank_address today, so show bank_name. Those two fields are not yet live on that account.
• The payer can use the rails in the option's rails list in capabilities.

Balances

• balance_details.available is the amount available to spend now. Use it when it is present.
• balance is in major units (dollars, euros). balance_source says where Gravv read it, wallet or institution.
• ledger_balance.posted and ledger_balance.projected are in minor units. With scale 2, 120000 is 1,200.00. Never show them as major units.

List accounts

GET /v2/accounts lists all your accounts, newest first.

curl --request GET \
     --url 'https://api.gravv.xyz/v2/accounts?customer_id=0b6f3c1e-2a4d-4c8e-9f10-7d2a6b5e4c33&currency=USD&limit=50&offset=0' \
     --header 'Api-Key: <API_KEY>'

{
  "data": {
    "items": [],
    "items_per_page": 50,
    "page": 1,
    "total_items": 0,
    "total_pages": 0
  },
  "error": null
}

You can filter by customer_id, excluded_customer_id, status, category, currency, network, bank_code, label (exact match), type, search, created_from and created_to. To find your business's own account and its customer id, filter by category=main. Page through the results with limit (1 to 200, default 50) and offset. Only these parameters work. Any other parameter returns 400 invalid request payload: unknown field "…", and a limit that is not a whole number returns 400.

Applications

GET /v2/accounts/applications lists applications, filtered by customer_id and status (lower case), with limit and offset. Its count is the number of items on the page, not a total. Applications not made with POST /v2/accounts appear too, and can have the status draft or submitted. Sandbox may not show them.