Skip to main content

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.

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. 
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,
    "cctpFast": true
  }'
FieldTypeDefaultDescription
codestringRequiredUnique gift code. Auto-generated if using bulk.
namestringRequiredHuman-readable name.
amountnumberRequiredUSDC amount per redemption.
tokenstring"USDC"Only USDC supported.
chainstring"STARKNET"Source chain for credits.
typestring"GIFT_CARD"GIFT_CARD, PROMOTIONAL, REFERRAL, LOYALTY, COMPENSATION.
maxRedeemsnumberRequiredTotal redemption limit across all users.
maxRedeemsPerUsernumberRequiredMax redeems per wallet address.
startsAtstringRequiredISO 8601 date when the code becomes active.
expiresAtstringnullOptional expiration date.
isActivebooleanRequiredCan be toggled to disable the code.
cctpFastbooleantrueFast CCTP mode (~5 sec, ~$0.01 fee) or standard (free, 4-8h).

​
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. 
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"}
    ]
  }'
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. 
curl https://api.chipipay.com/v1/gifts/claim/WELCOME5
Response (200)
{
  "valid": true,
  "gift": {
    "code": "WELCOME5",
    "name": "Welcome Bonus",
    "amount": "5",
    "token": "USDC",
    "chain": "STARKNET"
  },
  "orgName": "My App"
}
Invalid codes return: 
{"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. 
curl -X POST https://api.chipipay.com/v1/gifts/claim/WELCOME5/redeem \
  -H "Content-Type: application/json" \
  -d '{"walletAddress": "0x...", "chain": "starknet"}'
ChainResponseTime
starknet201 — instant, tx hash in response~3 sec
solana202 — CCTP bridge, poll status~24 sec
Starknet response (201): 
{
  "giftRedeem": {
    "id": "...",
    "status": "SUCCESS",
    "transactionHash": "0x...",
    "walletAddress": "0x...",
    "amount": "5"
  }
}
Solana response (202): 
{
  "redeemId": "...",
  "status": "BRIDGING",
  "destinationChain": "solana",
  "cctpBurnTxHash": "0x...",
  "estimatedSeconds": 24
}

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

Poll cross-chain redeem status. No auth required. 
curl https://api.chipipay.com/v1/gifts/claim/WELCOME5/status/REDEEM_ID

{
  "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_) 
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 StatusMeaning
201Gift created / Starknet redeem success
202Cross-chain redeem initiated (poll status)
400Invalid code, limit reached, insufficient credits
404Gift or redeem not found
500Server error (check manager wallet balance)