Developer Platform
View as Markdown Open in ChatGPT Open in Claude

Find an account option

Use GET /v1/accounts/capabilities to see which banks, currencies, networks and rails a customer can have.

API version: v2. The route is under /v1, but it returns v2 options and is the first step of a v2 account.

An option is one bank and currency a customer can open an account in. GET /v1/accounts/capabilities lists the options for one customer or one country. Pick one, and copy its bank_code into the next steps.

A money example. Ada lives in London and wants to receive 1,200.00 USD from a US client. You ask "what can a GB individual open in USD?" and get several options. The ones with a non-empty token_wallets are wallet-backed. On those, her 1,200.00 USD would arrive as USDC in the account's wallet.

Ask for the options

Send customer_id (or country when you have no customer yet), customer_type and currency. The request has no body and no Idempotency-Key:

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

Here is the response, trimmed to one option, two rails and two networks (checked in sandbox):

{
  "data": {
    "country": "GB",
    "customer_type": "individual",
    "subdivision": "GB-LND",
    "options": [
      {
        "account_types": ["card", "operating", "revenue", "yield"],
        "bank_code": "<bank_code>",
        "bank_name": "<bank name>",
        "categories": ["main", "sub_account"],
        "currency": "USD",
        "excluded_countries": ["AF", "IN", "KE"],
        "excluded_subdivisions": [],
        "features": {"collections": true, "internal_transfers": true},
        "max_accounts_per_customer": 20,
        "rails": [
          {"cost": "low", "currency": "USD", "description": "Domestic US bank transfers over the Automated Clearing House network.", "rail": "ach", "settlement_time": "1–3 business days", "title": "ACH"},
          {"cost": "medium", "currency": "USD", "description": "Domestic US wire transfer over Fedwire, for larger or faster transfers.", "rail": "wire", "settlement_time": "Same day", "title": "Wire"}
        ],
        "requires_customer_record": true,
        "token_wallets": [{"asset": "usdc", "network": "polygon"}, {"asset": "usdc", "network": "ethereum"}]
      }
    ]
  },
  "error": null
}

Read an option

Field What it tells you
bank_code The value to send as bank_code on requirements and create. Copy it. Do not hard-code it
currency The account currency
token_wallets If the list is not empty, the option is wallet-backed, and create must carry network (or wallet_id). If it is empty, the option is fiat-only, and create must carry neither
account_types Values you can send as account_type. Every option offers operating
categories Values you can send as category. Use sub_account for a customer's account
max_accounts_per_customer How many live accounts the customer can hold at this option. null means no limit. With customer_id, it includes any limit set for that customer
excluded_countries, excluded_subdivisions Where the option does not serve. Gravv already filters the list, so it leaves out an option that excludes the customer's country
rails How payers can send money in, such as ACH, wire, RTP, SEPA and Faster Payments. The list can be []
features Only the features that are on. A missing key means the feature is off. The key can be missing

Rules

  • Always send customer_type, even with customer_id. Without it, the list holds the options for both types, so the same bank_code can appear twice with different limits.
  • With customer_id, country and subdivision come from the customer's address. Without a customer, send country (alpha-2 or alpha-3) and, for the US, subdivision such as US-NY. The API does not refuse a subdivision that does not exist, but it then skips the state exclusions.
  • The API accepts lower-case currency=usd and country=gb.
  • An empty options list means nothing is available for that country and currency. The response then adds a suggestion text.
  • account_types lists the values you can send as account_type, such as operating, yield and revenue.
  • Sandbox and live can list different options, limits and exclusions. Read the options in each environment.

Errors

Response Why Fix
400 a customer country is required: supply country (ISO-3166 alpha-2) or a customer_id whose profile has an address No country, and the customer has no address Send country
400 invalid request payload: unknown field "limit" The API accepts only the documented query parameters Send only customer_id, country, subdivision, customer_type, currency
400 Customer ID must be a valid UUID, with details.customer_id Not a UUID Send the customer id
400 Customer Type "company" is not supported; valid values: individual, business Wrong customer_type Send individual or business
400 about currency (must be a 3-letter ISO-4217 code …) Bad currency format Send a 3-letter code
504 No response within 10 seconds Retry

Next

Read the requirements for the option you picked.

Was this page helpful?