Create a wallet
Creates a blockchain wallet for a customer on one network. The call is synchronous, so the response includes the address.
Every call creates a new wallet with a new address, even for the same customer and network. Reuse the Idempotency-Key to retry. A Stellar wallet finishes its trustline setup in the background, so it can take a short time before it can hold USDC.
Headers
Required for POST requests. Reuse it only to retry the same request. Each new key creates a new wallet.
Request Body
ID of the customer to create the wallet for. Gravv does not check that the customer exists, so check the ID before you send it.
Optional name for the wallet
Blockchain network, in lower case
Possible values: polygon, ethereum, avalanche, stellar, solana
Wallet type. A tenant can have one master wallet on each network.
Possible values: customer, master
Request Examples
{
"customer_id": "9e3cccad-e9ae-47a0-81ee-063af0159310",
"name": "my wallet",
"network": "stellar"
}
{
"customer_id": "9e3cccad-e9ae-47a0-81ee-063af0159310",
"name": "my wallet",
"network": "polygon"
}
Responses
| Status | Description |
|---|---|
200 |
The new wallet. It has no assets yet. |
400 |
The request failed. Errors include missing or invalid customer_id, missing or invalid network, invalid wallet_type, and tenant already has a master wallet on <network>. |
200 response
Wallet ID. Use it in GET /v1/wallets/{wallet_id} and as destination.id in a collection.
ID of the customer who owns this wallet
Blockchain address. The API returns EVM addresses in checksum case.
Blockchain network, in lower case
Possible values: polygon, ethereum, avalanche, stellar, solana
The name you gave, or the label wallet_<customer_id>_<network> when you gave none.
Wallet type
Possible values: customer, master
When the wallet was created, to the second
{
"data": {
"id": "2d52eb6d-4fac-44db-a225-d0e6aa13b0e3",
"address": "GDZQAF4A2E5VZMMQVW7XG4FKWZ5KDSUEZF5VQBDQVM53TMU2YLE54NTX",
"network": "stellar",
"name": "my wallet",
"date_created": "2026-10-12T09:14:03Z",
"customer_id": "9e3cccad-e9ae-47a0-81ee-063af0159310",
"wallet_type": "customer"
},
"error": null
}
400 response
{
"data": null,
"error": "missing or invalid customer_id"
}
Authorization
- ApiKeyAuth