Create a wallet

Create a stablecoin address for a customer on one network. Each call with a new key creates a new wallet.

This page shows how to create a stablecoin wallet for a customer on one network. Create a wallet returns the address at once.

Example. You create a Polygon wallet for Ada. The request times out before you see the response, so you retry with the same Idempotency-Key and get the same wallet back instead of a second address. Ada then receives 250 USDC on it.

Before you start

• Check that the customer exists with Get a customer. Gravv does not check customer_id on this call, so a typo creates a wallet that belongs to no customer.
• A scoped key needs account:create.
• Choose a network and coin that the sender supports. See Supported networks and coins.

Create the wallet

curl --request POST \
     --url https://api.gravv.xyz/v1/wallets \
     --header 'Api-Key: <API_KEY>' \
     --header 'Idempotency-Key: 5e6045ea-b883-4278-889e-882499155008' \
     --header 'Content-Type: application/json' \
     --data '
{
  "customer_id": "401d68fb-fe97-4c56-84a6-5651cdbde747",
  "network": "polygon",
  "name": "Ada top-up wallet"
}
'

{
  "data": {
    "id": "bbab27f6-04b8-457d-83ed-b92009758340",
    "address": "0xc47B2D22812ee674Ee5182320FCCA83854f21962",
    "network": "polygon",
    "name": "Ada top-up wallet",
    "date_created": "2026-10-13T09:14:03Z",
    "customer_id": "401d68fb-fe97-4c56-84a6-5651cdbde747",
    "wallet_type": "customer"
  },
  "error": null
}

• Store id and address exactly as returned. EVM addresses come back in mixed (checksum) case, and the wallet_address filter matches case-sensitively.
• Every call with a new Idempotency-Key creates a new wallet with a new address. Use one key per wallet you mean to create, and reuse it only to retry after a timeout.
• Gravv does not send a webhook when it creates a wallet.
• Gravv sets up a Stellar wallet's USDC trustline in the background, within seconds. Ask a Stellar sender to try a small amount first.

What can go wrong