Provider Console

Create Giveaways and Issue Entries

Apply to become a provider, then create giveaways and issue entries from this dashboard.

Wallet

Required network: Base Sepolia (84532)

Current chain id: -

Connected wallet: Not connected

Wallet balance (ETH): -

Provider active: -

ProviderRegistry: 0x09d2ff08E0f83557522ee166328322cF341EE0BF

GiveawayEntries: 0x7F7044131f019c936D8c9E9608AdC7b533aCCf41

Provider Data

My Giveaways

All indexed giveaways created by the connected provider wallet.

Giveaway ID	Mode	Handshake	Receipt Gas Payer	Rolling	Start	End	Metadata	Block	Tx	Actions
Connect provider wallet to view giveaways.

On-Chain Actions

Create Giveaway

Giveaway ID (text or 0x bytes32)Start (unix seconds, optional)End (unix seconds, optional)

Determination TypeLearn more

Require winner handshake (winner must confirm receipt)Provider pays receipt confirmation gas

Rolling repeat every X days (0 = off)Rolling active for Y days

Carry over all entries between rolling rounds

Rolling uses start time as anchor. Example: X=7, Y=7 means continuous weekly rounds.

Title (optional)Description (optional)Image URL (optional)Metadata URI

If Metadata URI is empty, the dashboard auto-builds an on-chain data URI from title/description/image.

Manage Entries

Pick from My Giveaways (optional)Giveaway ID (text or 0x bytes32)Passport IDAmountActionReasonEvidence (text or 0x bytes32)

Winner Actions

Use after giveaway end time. Provider mode uses Declare Winner; on-chain-random mode uses Draw Winner.

Winner Passport ID (for provider mode)

Prize Round Index (0 for non-rolling)Proof Chain IDRound Metadata URI (optional explicit)Round TitleRound Item Image URLRound DescriptionWinner Image URLAsset Contract (ERC20/ERC721/ERC1155)Recipient WalletProof Tx Hash (text or 0x bytes32)Proof URI (optional explorer link)

Integration

API Integration

Use provider API keys to integrate giveaway creation and entry issuance from your backend systems.

Provider Signer (Default)

This signer is used by all API keys unless a key-level signer is attached.

What this signer does

The server signer is the wallet used by the API to sign and broadcast provider transactions (create giveaways, issue/remove entries, declare winners) so your backend can operate securely without a browser popup.

Use a dedicated provider signer key with only the required funds/permissions. Keep enough Base Sepolia ETH for gas.

Learn More

Provider Signer Private Key (0x...)

Use the private key for this provider wallet. Format must be `0x` plus 64 hex characters.

Configured: no

Signer address: -

Last used: -

Manage API Keys

Key LabelKey-level Signer Private Key (optional override)

Optional. If empty, this key uses the default provider signer above. Format must be `0x` plus 64 hex characters.

No API keys yet.

Integration Endpoints

Quick Start

Create API key in this dashboard.
Configure provider signer (or key-level signer override).
Call create-giveaway, then issue-entries/remove-entries as needed.
Handle responses by checking `ok`; only treat action as complete when `ok=true`.

Required Headers

x-api-key: <provider_api_key>
content-type: application/json

Success Response (all endpoints)

{
  "ok": true,
  "requestId": "...",
  "status": "submitted",
  "retryable": false,
  "txHash": "0x..."
}

Create Giveaway

POST /api/provider/integrations/create-giveaway

Request Body

{
  "giveawayId": "giveaway-001",
  "startTime": 1771809363,
  "endTime": 1772414163,
  "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": ""
}

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

Error Handling Rules

Common error codes: `INSUFFICIENT_FUNDS`, `NONCE_TOO_LOW`, `FEE_TOO_LOW`, `RPC_RATE_LIMIT`, `CONTRACT_REVERT`, `SIGNER_NOT_CONFIGURED`, `UNAUTHORIZED`.

Integration rule: only mark your internal action complete when `ok=true`. If `ok=false`, stop flow, follow `recommendedAction`, and retry only when `retryable=true`.

LLM Integration Guide (.md)

Full markdown guide for AI agents and developers to integrate provider flows end-to-end.

# Giveaway Passport Provider Integration Guide

Use this guide to integrate Giveaway Passport provider endpoints safely and correctly.

## Network
- Base Layer 2 (Base Sepolia in current environment)

## Authentication
```http
x-api-key: <provider_api_key>
content-type: application/json
```

## Endpoint Order (Typical)
1. Create giveaway
2. Issue/remove entries
3. Finalize winner (declare or draw)
4. Optional: confirm receipt, record prize delivery

## Endpoints
```http
POST /api/provider/integrations/create-giveaway
POST /api/provider/integrations/issue-entries
POST /api/provider/integrations/remove-entries
POST /api/provider/integrations/declare-winner
POST /api/provider/integrations/draw-winner
POST /api/provider/integrations/set-round-metadata
POST /api/provider/integrations/set-round-image
POST /api/provider/integrations/confirm-receipt-by-provider
POST /api/provider/integrations/record-prize-delivery
POST /api/provider/integrations/passport-contact
GET  /api/provider/integrations/passport-status?passportId=<id>
POST /api/provider/integrations/provision-entrant
```

## Standard Success Response
```json
{
  "ok": true,
  "requestId": "...",
  "status": "submitted",
  "retryable": false,
  "txHash": "0x..."
}
```

## Standard Failure Response
```json
{
  "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"
  }
}
```

## Critical Integration Rule
- Only mark internal action complete when `ok=true`.
- If `ok=false`, stop flow and apply `recommendedAction`.
- Retry only when `retryable=true`.

## Error Codes to Handle
- INSUFFICIENT_FUNDS
- NONCE_TOO_LOW
- FEE_TOO_LOW
- RPC_RATE_LIMIT
- CONTRACT_REVERT
- SIGNER_NOT_CONFIGURED
- UNAUTHORIZED