Retrieve cards

Read one card, or list cards by cardholder, status or type, and see which fields differ between the two answers.

This page shows how to read one card or a list of cards. Get card returns one card. List cards returns a page of cards, newest first. Neither returns the full card number. To read it, use sensitive details.

A money example. Ada has two cards: her main card (300 USD a day) and a subscriptions card (50 USD a day). GET /v1/cards?customer_id=…&status=active,freeze,inactive returns both. She can hold 8 more cards before she reaches the cap of 10.

Read one card

curl --request GET \
     --url https://api.gravv.xyz/v1/cards/a14ec356-f33d-4384-ba68-4d9bfa19765b \
     --header 'Api-Key: <API_KEY>'

{
  "data": {
    "id": "a14ec356-f33d-4384-ba68-4d9bfa19765b",
    "date_created": "2026-10-13T10:48:18.170061Z",
    "date_updated": "2026-10-13T15:31:40.273281Z",
    "name_on_card": "Ada Obi",
    "customer_id": "5b0f6c1e-2a8f-4c39-9d0e-0c7e3b9a1f42",
    "blockchain_network": "polygon",
    "proxy_address": null,
    "masked_pan": "*******9351",
    "expiry": "07/2029",
    "network": "visa",
    "currency": "USD",
    "asset": "USDC",
    "card_type": "virtual",
    "status": "active",
    "billing_address": null,
    "shipping_address": null,
    "spending_controls": {
      "type": "virtual",
      "activated": true,
      "daily_transaction_limit": 300
    }
  },
  "error": null
}

spending_controls.daily_transaction_limit is the card's only limit, in whole US dollars per day. Read it before every status update, because the update must send it back.

List cards

curl --request GET \
     --url 'https://api.gravv.xyz/v1/cards?customer_id=5b0f6c1e-2a8f-4c39-9d0e-0c7e3b9a1f42&status=active,freeze,inactive&page=1&items_per_page=20' \
     --header 'Api-Key: <API_KEY>'

{
  "data": {
    "items": [
      {
        "id": "a14ec356-f33d-4384-ba68-4d9bfa19765b",
        "customer_id": "5b0f6c1e-2a8f-4c39-9d0e-0c7e3b9a1f42",
        "date_created": "2026-10-13T10:48:18.170061Z",
        "date_updated": "2026-10-13T15:31:40.273281Z",
        "name_on_card": "Ada Obi",
        "blockchain_network": "polygon",
        "masked_pan": "9351",
        "expiry": "7/2029",
        "network": "visa",
        "currency": "USD",
        "asset": "USDC",
        "status": "active",
        "card_type": "virtual",
        "wallet_address": "0xa10a5f695dfe578a13b2d618a8ea8679d8d2036d",
        "account_id": "9b40be8d-9d74-4d2a-8897-dea3ef80ad23",
        "proxy_address": null,
        "address": null
      }
    ],
    "items_per_page": 20,
    "page": 1,
    "total_items": 1,
    "total_pages": 1
  },
  "error": null
}

Query	What it does
customer_id	Returns one cardholder's cards
card_id	Returns one card, in the list shape (with account_id and wallet_address)
status	Filters by one or more of active, freeze, blocked, inactive, separated by commas
card_type	Filters by virtual, physical, or both, separated by commas
page, items_per_page	Pages start at 1. The default page size is 10

The list also includes applications that have no card yet. These rows have an empty status. Send status=active,freeze,blocked,inactive to list cards only.

Where the two answers differ

Field	Get card	List cards
masked_pan	*******9351	9351
expiry	07/2029	7/2029
spending_controls, shipping_address, billing_address	Yes	No
account_id, wallet_address	No	Yes

Sandbox cards show expiry as YYYY-MM-DD, so your code must parse every format. A card that failed to issue can show an empty status, expiry and masked_pan. You cannot use it.

A wrong card id returns 400 card does not exist. Every card error is a 400.