> ## 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.
</Note>

## At a glance

<CardGroup cols={4}>
  <Card title="Funded from credits" icon="wallet">
    USDC held on Chipi's Starknet treasury; created code is a claim on that hold
  </Card>

  <Card title="Two destination chains" icon="link">
    Recipient picks Starknet or Solana at redeem time
  </Card>

  <Card title="Per-code limits" icon="users">
    `maxRedeems` (total) + `maxRedeemsPerUser`
  </Card>

  <Card title="5 gift types" icon="gift">
    PROMOTIONAL, GIFT\_CARD, REFERRAL, LOYALTY, COMPENSATION
  </Card>
</CardGroup>

## 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.