Endpoints

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
  }'

{
  "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.

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.

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"}
    ]
  }'

{
  "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.

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"}'

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):

{
  "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 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)

Gasless Wallets

Bill Payments

AI API

Gift Cards

Billing & Credits

POST /gifts

POST /gifts/bulk

GET /gifts/claim/:code

POST /gifts/claim/:code/redeem

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

GET /gifts

PATCH /gifts/:id

DELETE /gifts/:id

Error handling

​POST /gifts

​POST /gifts/bulk

​GET /gifts/claim/:code

​POST /gifts/claim/:code/redeem

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

​GET /gifts

​PATCH /gifts/:id

​DELETE /gifts/:id

​Error handling

POST /gifts

POST /gifts/bulk

GET /gifts/claim/:code

POST /gifts/claim/:code/redeem

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

GET /gifts

PATCH /gifts/:id

DELETE /gifts/:id

Error handling