Skip to content
Gave

Quickstart

From a funded vault to a reward in your user's balance, in four requests.

You need a sandbox API key and your integrator ID, which Gave gives you. For now, Gave also sets up your webhook endpoint and gives you its signing secret. The examples use the integrator ID acme: replace it with yours.

export GAVE_API_KEY=... # your sandbox key: keep it on your servers

Check the API

curl -i https://api.sandbox.gave.sh/health

It answers 204 No Content.

Fund the sandbox vault

Rewards are reserved in your vault, so put money in it first. This deposits 100 USDC in the simulated vault:

curl https://api.sandbox.gave.sh/v1/sandbox/deposits \
  -H "x-api-key: $GAVE_API_KEY" \
  -H "content-type: application/json" \
  -d @deposit.json
deposit.json
{
  "reference": "deposit-0001",
  "amount": { "asset": "USDC", "amount": "100000000" }
}

You get a vault.deposit_confirmed webhook. See Sandbox vault.

Send a purchase

A clearing is a settled card transaction: here, 50.00 USD at a coffee shop for your user alice.

curl https://api.sandbox.gave.sh/v1/spend-events \
  -H "x-api-key: $GAVE_API_KEY" \
  -H "content-type: application/json" \
  -d @clearing.json
clearing.json
{
  "kind": "clearing",
  "integratorId": "acme",
  "userId": "alice",
  "externalTransactionId": "txn_0001",
  "amount": { "currency": "USD", "amount": "5000" },
  "merchant": { "descriptor": "BLUE BOTTLE COFFEE", "mcc": "5814", "country": "US" },
  "occurredAt": "2026-10-11T09:30:00.000Z"
}

The event is stored before Gave answers 202 Accepted, and processed right after:

SpendEventAccepted
{ "id": "se:acme:alice:clearing:txn_0001", "duplicate": false }

Read the reward

curl https://api.sandbox.gave.sh/v1/users/alice/balance \
  -H "x-api-key: $GAVE_API_KEY"

With a program paying 1%, the purchase earned 0.50 USDC, pending until its holding period ends:

UserBalance
{
  "userId": "alice",
  "balances": [
    { "asset": "USDC", "expected": "0", "pending": "500000", "claimable": "0", "paid": "0", "owed": "0" },
    { "asset": "EURe", "expected": "0", "pending": "0", "claimable": "0", "paid": "0", "owed": "0" }
  ]
}

Your webhook endpoint receives the same reward as a reward.pending event. See Webhooks to verify and handle it.

Next

  • Spend events: every kind of card transaction, and how retries work.
  • Webhooks: the events, their signatures, and how deliveries are retried.
  • Errors: what each error means, and which ones to retry.