> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chipipay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Gift Cards

> Send USDC to anyone via a redeemable code. Funded from your Chipi credits balance; recipient claims on Starknet or Solana — cross-chain bridging happens automatically.

> [!NOTE]
>
> Gift Cards are **live**. You pre-fund Chipi credits in USDC, mint a redeemable `code`, share it however you want, and the recipient claims into a Starknet or Solana wallet. Cross-chain delivery uses Circle's CCTP bridge under the hood.

## At a glance

> **Funded from credits**
>
> USDC held on Chipi's Starknet treasury; created code is a claim on that hold

> **Two destination chains**
>
> Recipient picks Starknet or Solana at redeem time

> **Per-code limits**
>
> `maxRedeems` (total) + `maxRedeemsPerUser`

> **5 gift types**
>
> PROMOTIONAL, GIFT\_CARD, REFERRAL, LOYALTY, COMPENSATION

## How it works

1. **You create a gift code** via `POST /v1/gifts` with an amount, expiry, and per-user/total redeem caps. Chipi holds the total potential payout (`amount × maxRedeems`) from your credits balance on creation, so no over-spend.
2. **You share the code** any way you like — email, link in your app, QR. The `code` is the redeem key.
3. **A recipient redeems** via `POST /v1/gifts/claim/:code/redeem` with their wallet address and target chain. Starknet recipients receive instantly; Solana recipients go through CCTP burn → Circle attestation → mint on Solana (status transitions visible via the redeem polling endpoint).

The redeem endpoint is public (no API key required) so the code itself is the access token — share carefully.

## Endpoints

All under `/v1/gifts/*` on `https://api.chipipay.com`. Org-facing endpoints (create, list, stats) use `ApiKeyGuard` (sk\_ in `Authorization` OR pk\_ in `x-api-key`); claim/status endpoints are public.

| Method + path | Auth | Purpose |
| - | - | - |
| `POST /v1/gifts` | ApiKeyGuard | Create a gift code |
| `POST /v1/gifts/bulk` | ApiKeyGuard | Create N codes in one call |
| `GET /v1/gifts` | ApiKeyGuard | List your org's codes |
| `GET /v1/gifts/:id` | ApiKeyGuard | Single code detail |
| `GET /v1/gifts/usage` | ApiKeyGuard | Aggregate redeem stats for your org |
| `GET /v1/gifts/history/redeems` | ApiKeyGuard | List redeems against your codes |
| `GET /v1/gifts/history/redeems/:id` | ApiKeyGuard | Single redeem detail |
| `GET /v1/gifts/claim/:code` | Public | Recipient previews the code (amount, expiry, etc.) |
| `POST /v1/gifts/claim/:code/redeem` | Public | Recipient claims into their wallet |
| `GET /v1/gifts/claim/:code/status/:redeemId` | Public | Recipient polls redeem status |
| `GET /v1/gifts/redeems/:id/status` | ApiKeyGuard | Org-side polling on a specific redeem |

## Cross-chain delivery

| Recipient picks | Path | Typical latency |
| - | - | - |
| `chain: "starknet"` | Direct transfer from Chipi's Starknet treasury | Seconds (one Starknet tx) |
| `chain: "solana"` | CCTP burn on Starknet → Circle attestation → mint on Solana | 60–120 seconds (Circle attestation gates it) |

The Solana path tracks state through `GiftRedeemStatus`: `PENDING` → `BRIDGING` (CCTP burn submitted) → `ATTESTED` (attestation received from Circle) → `SUCCESS` (USDC minted on Solana). Recipients poll the public status endpoint.

If anything fails between BRIDGING and SUCCESS, the redeem moves to `FAILED` and the hold against your credits is released. You're not charged for failed redeems.

## Gift types

The `type` field on every gift is one of:

* `PROMOTIONAL` — marketing campaigns, sign-up bonuses
* `GIFT_CARD` — explicit gift product (e.g. a \$25 USDC card)
* `REFERRAL` — referral rewards
* `LOYALTY` — repeat-customer rewards
* `COMPENSATION` — refunds or make-goods

Chipi treats them identically functionally; the field exists for your own analytics + compliance reporting.

## Where to go next

* **[Quickstart](/services/gift-cards/quickstart)** — first `POST /v1/gifts` call to create a code, then claim it.
* **[Endpoints](/services/gift-cards/endpoints)** — full request/response shapes per route.
* **[Cross-chain](/services/gift-cards/cross-chain)** — CCTP wire details, Solana recipient flow.
* **[Dashboard](/services/gift-cards/dashboard)** — org-side admin: bulk create, view stats, retire codes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.