Create Giveaway
POST /api/provider/integrations/create-giveaway
Request Body
{
"giveawayId": "giveaway-001",
"startTime": 1771809363,
"endTime": 0,
"determinationType": 1,
"requiresHandshake": true,
"providerPaysReceiptGas": true,
"rollingEveryDays": 7,
"rollingActiveDays": 7,
"rollingEntriesCarryOver": true,
"title": "Weekly Giveaway",
"description": "Win prizes by collecting entries",
"image": "https://provider.example/giveaway.png",
"metadataUri": ""
}For rolling giveaways, startTime is the exact start of round 1 and the anchor for all later rounds. endTime is the optional final campaign cutoff; use 0 or omit it for no final end date.
Failure Response
{
"ok": false,
"requestId": "...",
"error": {
"code": "CONTRACT_REVERT",
"message": "...",
"retryable": false,
"recommendedAction": "Fix the request payload and retry."
},
"context": {
"endpoint": "create-giveaway"
}
}Issue Entries
POST /api/provider/integrations/issue-entries
Request Body
{
"giveawayId": "giveaway-001",
"passportId": 1,
"amount": 25,
"reasonCode": 999,
"evidence": "internal-record-123",
"expectedOwnerWallet": "0xentrant..."
}Failure Response
{
"ok": false,
"requestId": "...",
"error": {
"code": "INSUFFICIENT_FUNDS",
"message": "...",
"retryable": false,
"recommendedAction": "Top up provider signer wallet with Base Sepolia ETH, then retry."
},
"context": {
"endpoint": "issue-entries"
}
}Remove Entries
POST /api/provider/integrations/remove-entries
Request Body
{
"giveawayId": "giveaway-001",
"passportId": 1,
"amount": 5,
"reasonCode": 999,
"evidence": "refund-or-reversal-123",
"expectedOwnerWallet": "0xentrant..."
}Failure Response
{
"ok": false,
"requestId": "...",
"error": {
"code": "CONTRACT_REVERT",
"message": "...",
"retryable": false,
"recommendedAction": "Check giveaway/passport state and retry with valid values."
},
"context": {
"endpoint": "remove-entries"
}
}Declare Winner (provider mode)
POST /api/provider/integrations/declare-winner
Request Body
{
"giveawayId": "giveaway-001",
"passportId": 1
}Failure Response
{
"ok": false,
"requestId": "...",
"error": {
"code": "CONTRACT_REVERT",
"message": "...",
"retryable": false,
"recommendedAction": "Ensure giveaway is in provider determination mode and has ended."
},
"context": {
"endpoint": "declare-winner"
}
}Draw Winner (on-chain-random mode)
POST /api/provider/integrations/draw-winner
Request Body
{
"giveawayId": "giveaway-001"
}Failure Response
{
"ok": false,
"requestId": "...",
"error": {
"code": "CONTRACT_REVERT",
"message": "...",
"retryable": false,
"recommendedAction": "Ensure giveaway is configured for on-chain random and has ended."
},
"context": {
"endpoint": "draw-winner"
}
}Confirm Receipt by Provider
POST /api/provider/integrations/confirm-receipt-by-provider
Request Body
{
"giveawayId": "giveaway-001"
}Failure Response
{
"ok": false,
"requestId": "...",
"error": {
"code": "CONTRACT_REVERT",
"message": "...",
"retryable": false,
"recommendedAction": "Use only after winner selection when provider-paid receipt mode is enabled."
},
"context": {
"endpoint": "confirm-receipt-by-provider"
}
}Set Round Metadata
POST /api/provider/integrations/set-round-metadata
Request Body
{
"giveawayId": "giveaway-001",
"roundIndex": 0,
"metadataUri": "",
"title": "Round 1 Prize",
"description": "Signed collector bundle",
"itemImage": "https://provider.example/round-1-item.png",
"winnerImage": "https://provider.example/round-1-winner.png"
}Failure Response
{
"ok": false,
"requestId": "...",
"error": {
"code": "WINNER_NOT_DECLARED",
"message": "...",
"retryable": false,
"recommendedAction": "Declare or draw the winner first, then retry."
},
"context": {
"endpoint": "set-round-metadata"
}
}Set Winner Image
POST /api/provider/integrations/set-round-image
Request Body
{
"giveawayId": "giveaway-001",
"roundIndex": 0,
"imageURI": "https://provider.example/round-1-winner.png"
}Failure Response
{
"ok": false,
"requestId": "...",
"error": {
"code": "WINNER_NOT_DECLARED",
"message": "...",
"retryable": false,
"recommendedAction": "Declare or draw the winner first, then retry."
},
"context": {
"endpoint": "set-round-image"
}
}Record Prize Delivery Proof
POST /api/provider/integrations/record-prize-delivery
Request Body
{
"giveawayId": "giveaway-001",
"roundIndex": 0,
"assetContract": "0xTokenOrNftContract...",
"recipient": "0xWinnerWallet...",
"proofChainId": 84532,
"proofTxHash": "0x...",
"proofURI": "https://sepolia.basescan.org/tx/0x..."
}Failure Response
{
"ok": false,
"requestId": "...",
"error": {
"code": "CONTRACT_REVERT",
"message": "...",
"retryable": false,
"recommendedAction": "Declare a winner first and use valid round index/proof fields."
},
"context": {
"endpoint": "record-prize-delivery"
}
}Passport Contact
POST /api/provider/integrations/passport-contact
Request Body
{
"passportId": 1
}Failure Response
{
"ok": false,
"requestId": "...",
"error": {
"code": "UNAUTHORIZED",
"message": "...",
"retryable": false,
"recommendedAction": "Request contact only for data explicitly shared with your provider wallet."
},
"context": {
"endpoint": "passport-contact"
}
}Passport Status (ownership reconciliation)
GET /api/provider/integrations/passport-status?passportId=1
Use before issuing/removing entries to reconcile external transfers and avoid writing against stale owner mappings.
Provision Entrant (mint + optional issue)
POST /api/provider/integrations/provision-entrant
Request Body
// 1) Direct entrant wallet (default) + notify email
{
"ownershipMode": "direct_entrant_wallet",
"entrantWallet": "0xabc...",
"giveawayId": "giveaway-001",
"amount": 25,
"reasonCode": 999,
"evidence": "internal-record-123",
"notify": true,
"email": "entrant@example.com",
"claimUrl": "https://provider.example/claim?token=..."
}
// 2) Managed wallet (server generates if managedWallet omitted)
{
"ownershipMode": "managed_wallet",
"entrantWallet": "0xoptional-business-reference-wallet",
"managedWallet": "",
"giveawayId": "giveaway-001",
"amount": 25,
"reasonCode": 999,
"notify": true,
"email": "entrant@example.com"
}
// 3) Transfer existing passport
{
"ownershipMode": "transfer_existing_passport",
"entrantWallet": "0xtarget...",
"sourceWallet": "0xsource...",
"issue": false,
"notify": true,
"email": "entrant@example.com"
}The platform supports all three ownership scenarios: mint to entrant wallet, mint to managed wallet, or transfer an existing passport to entrant wallet.
Transferability: pass maxTransfers when minting. 0=non-tradable, 1=one transfer, omit for unlimited.
Failure Response
{
"ok": false,
"requestId": "...",
"error": {
"code": "SIGNER_NOT_CONFIGURED",
"message": "...",
"retryable": false,
"recommendedAction": "Attach a signer to this API key or configure a provider default signer."
},
"context": {
"endpoint": "provision-entrant"
}
}