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

# Endpoints

> All Gift Cards API endpoints — create, validate, redeem, bulk, status.

Base URL: `https://api.chipipay.com/v1`

***

## POST /gifts

Create a redeemable gift code. Credits are held from your org balance.

**Auth:** `Authorization: Bearer sk_...` or `x-api-key: pk_...`

**Cost:** No per-call fee. Credits held = `amount × maxRedeems + gas estimate`.

```bash Request theme={null}
curl -X POST https://api.chipipay.com/v1/gifts \
  -H "Authorization: Bearer sk_prod_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "WELCOME5",
    "name": "Welcome Bonus",
    "amount": 5,
    "token": "USDC",
    "chain": "STARKNET",
    "type": "GIFT_CARD",
    "maxRedeems": 100,
    "maxRedeemsPerUser": 1,
    "startsAt": "2026-01-01T00:00:00Z",
    "isActive": true
  }'
```

```json Response (201) theme={null}
{
  "id": "a9bf75ca-de8b-489a-bdb0-88767bd7a47a",
  "code": "WELCOME5",
  "name": "Welcome Bonus",
  "amount": "5",
  "token": "USDC",
  "chain": "STARKNET",
  "type": "GIFT_CARD",
  "maxRedeems": 100,
  "maxRedeemsPerUser": 1,
  "totalRedeems": 0,
  "startsAt": "2026-01-01T00:00:00.000Z",
  "expiresAt": null,
  "isActive": true,
  "cctpFast": true,
  "holdLedgerEntryId": null,
  "totalHeldUsd": null,
  "totalRedeemedUsd": null,
  "recipientEmail": null,
  "campaignName": null
}
```

| Field | Type | Default | Description |
| - | - | - | - |
| `code` | string | Required | Unique gift code. Auto-generated if using bulk. |
| `name` | string | Required | Human-readable name. |
| `amount` | number | Required | USDC amount per redemption. |
| `token` | string | `"USDC"` | Only USDC supported. |
| `chain` | string | `"STARKNET"` | Source chain for credits. |
| `type` | string | `"GIFT_CARD"` | GIFT\_CARD, PROMOTIONAL, REFERRAL, LOYALTY, COMPENSATION. |
| `maxRedeems` | number | Required | Total redemption limit across all users. |
| `maxRedeemsPerUser` | number | Required | Max redeems per wallet address. |
| `startsAt` | string | Required | ISO 8601 date when the code becomes active. |
| `expiresAt` | string | null | Optional expiration date. |
| `isActive` | boolean | Required | Can be toggled to disable the code. |

> [!NOTE]
>
> `cctpFast` (fast vs standard CCTP for Solana redeems) is **not configurable on single-create** today. The Gift row defaults to `cctpFast: true` server-side. To override, use `POST /gifts/bulk` (which does accept `cctpFast` in the request body) or the dashboard's bulk-airdrop flow.

***

## POST /gifts/bulk

Create multiple gift codes + send claim emails. One gift per recipient.

**Auth:** `Authorization: Bearer sk_...` or `x-api-key: pk_...`

**Max:** 500 recipients per batch.

```bash Request theme={null}
curl -X POST https://api.chipipay.com/v1/gifts/bulk \
  -H "Authorization: Bearer sk_prod_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "May Airdrop",
    "amount": 5,
    "token": "USDC",
    "chain": "STARKNET",
    "type": "GIFT_CARD",
    "cctpFast": true,
    "recipients": [
      {"email": "alice@example.com"},
      {"email": "bob@example.com", "code": "BOB_SPECIAL"}
    ]
  }'
```

```json Response (201) theme={null}
{
  "created": 2,
  "campaignName": "May Airdrop",
  "totalHeldUsd": 10.01,
  "gifts": [
    {"code": "A1B2C3D4", "email": "alice@example.com", "claimUrl": "https://dashboard.chipipay.com/claim/A1B2C3D4"},
    {"code": "BOB_SPECIAL", "email": "bob@example.com", "claimUrl": "https://dashboard.chipipay.com/claim/BOB_SPECIAL"}
  ]
}
```

Each recipient receives an email with a "Claim Your Gift" button linking to the claim page. Codes are auto-generated (8-char uppercase) unless you provide a custom code.

***

## GET /gifts/claim/:code

Validate a gift code. **No auth required** — the code is the credential.

Used by the claim page to show "You received \$5 USDC from Org Name" before the user enters their wallet.

```bash theme={null}
curl https://api.chipipay.com/v1/gifts/claim/WELCOME5
```

```json Response (200) theme={null}
{
  "valid": true,
  "gift": {
    "code": "WELCOME5",
    "name": "Welcome Bonus",
    "amount": "5",
    "token": "USDC",
    "chain": "STARKNET"
  },
  "orgName": "My App"
}
```

Invalid codes return:

```json theme={null}
{"valid": false, "reason": "Gift has expired"}
{"valid": false, "reason": "Gift redemption limit reached"}
{"valid": false, "reason": "Gift not found"}
```

Returns `{ "valid": false, "reason": "Gift has expired" }` if the code is invalid.

***

## POST /gifts/claim/:code/redeem

Redeem a gift code — sends USDC to the provided wallet address. **No auth required.**

```bash Starknet (instant) theme={null}
curl -X POST https://api.chipipay.com/v1/gifts/claim/WELCOME5/redeem \
  -H "Content-Type: application/json" \
  -d '{"walletAddress": "0x...", "chain": "starknet"}'
```

```bash Solana (CCTP, ~24 sec) theme={null}
curl -X POST https://api.chipipay.com/v1/gifts/claim/WELCOME5/redeem \
  -H "Content-Type: application/json" \
  -d '{"walletAddress": "FZQq...", "chain": "solana"}'
```

| Chain | Response | Time |
| - | - | - |
| `starknet` | 201 — instant, tx hash in response | \~3 sec |
| `solana` | 202 — CCTP bridge, poll status | \~24 sec |

**Starknet response (201):**

```json theme={null}
{
  "giftRedeem": {
    "id": "...",
    "status": "SUCCESS",
    "transactionHash": "0x...",
    "walletAddress": "0x...",
    "amount": "5"
  }
}
```

**Solana response (202):**

```json theme={null}
{
  "redeemId": "...",
  "status": "BRIDGING",
  "destinationChain": "solana",
  "cctpBurnTxHash": "0x...",
  "estimatedSeconds": 24
}
```

***

## GET /gifts/claim/:code/status/:redeemId

Poll cross-chain redeem status. **No auth required.**

```bash theme={null}
curl https://api.chipipay.com/v1/gifts/claim/WELCOME5/status/REDEEM_ID
```

```json theme={null}
{
  "id": "...",
  "status": "SUCCESS",
  "destinationChain": "solana",
  "cctpBurnTxHash": "0x...",
  "receiveChainTxHash": "3xxK3y...",
  "amount": 5
}
```

Status flow: `PENDING → BRIDGING → ATTESTED → SUCCESS`

If `FAILED`: the Starknet burn tx is in `cctpBurnTxHash` — the funds may still be recoverable.

***

## GET /gifts

List all gift codes for your org.

**Auth:** Required (sk\_/pk\_)

```bash theme={null}
curl https://api.chipipay.com/v1/gifts \
  -H "Authorization: Bearer sk_prod_YOUR_KEY"
```

***

## PATCH /gifts/:id

Update a gift (toggle active, change name, expiry).

**Auth:** Required (sk\_/pk\_)

***

## DELETE /gifts/:id

Delete a gift and release held credits.

**Auth:** Required (sk\_/pk\_)

***

## Error handling

| HTTP Status | Meaning |
| - | - |
| 201 | Gift created / Starknet redeem success |
| 202 | Cross-chain redeem initiated (poll status) |
| 400 | Invalid code, limit reached, insufficient credits |
| 404 | Gift or redeem not found |
| 500 | Server error (check manager wallet balance) |


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