Partner API task

Request and answer

What we send your endpoint and what to answer.

The API task lets a campaign ask your own server whether a wallet did something in your app. When a participant presses Verify, we call your endpoint with their wallet and you answer done or not done. The call uses Zealy's API task format, so an endpoint built for Zealy works here as it is. Setting the task up in a campaign is covered in Tasks and raffle tickets.

Request

A POST to the https endpoint you saved in the task, with a JSON body:

POST https://your.app/check
content-type: application/json
x-api-key: <your key, when you saved one>

{
  "userId": "0xabc…",
  "communityId": "your-partner-slug",
  "subdomain": "your-partner-slug",
  "questId": "412",
  "requestId": "6f1c2e7a-…",
  "accounts": { "wallet": "0xabc…" },
  "blockchain": "base",
  "chainId": 8453,
  "campaignId": "abcde"
}
FieldWhat it is
userIdThe participant's wallet, in lowercase.
accounts.walletThe same wallet. It is the only thing about the participant we send.
communityId, subdomainYour partner slug, in both.
questIdThe task's id. It stays the same once the campaign starts.
requestIdA new UUID for each call.
blockchain, chainIdThe chain you picked in the task. The wallet is the same address on every chain.
campaignIdThe campaign's code.
blockchainchainId
base8453
robinhood4663
ethereum1
optimism10
arbitrum42161
polygon137
bsc56
HeaderWhen
content-type: application/jsonAlways.
user-agent: GiftedStock-Tasks/1 (+https://www.giftedstock.com)Always.
x-api-keyWhen you saved an API key in the task.
x-giftedstock-timestamp, x-giftedstock-signatureWhen you saved a key: see Signed calls.
Since 17 Nov 2026 the call carries the wallet only. accounts.twitter is never sent, also for tasks saved before with the wallet and X.

Your answer

You answerWhat the participant sees
200Done. A body is optional.
400 with { "message": "…" }Not done, with your message. Without one: "not done yet".
Anything else or nothing within 10 secondsYour API did not answer, try again in a minute. This is not a failed task.
  • Your message is shown as one line of plain text, at most 200 characters, with control and text-direction characters taken out.
  • There are no raffle tickets on this task: it is done or not done.
  • We read at most 16 KB of your answer and follow no redirects. The endpoint must be https on a public address.

A smallest endpoint, in Node:

import { createServer } from "node:http";

createServer(async (req, res) => {
  let body = "";
  for await (const chunk of req) body += chunk;
  const { accounts } = JSON.parse(body);
  const done = await didTheTask(accounts.wallet); // your own check
  res.writeHead(done ? 200 : 400, { "content-type": "application/json" });
  res.end(JSON.stringify(done ? {} : { message: "make one trade on our app first" }));
}).listen(8080);

Before we call

Each Verify asks the participant's wallet to sign one line first, naming the task and that their wallet goes to you. So only a wallet's owner can have it checked. Nobody can read your answer about a wallet that is not theirs. The signature is free and offchain.

Test it from the campaign form

  1. Step 1: Fill in the task

    The endpoint, your API key (optional) and the blockchain.

  2. Step 2: Pick a test wallet

    Any address. Leave it empty to use the wallet you are signed in with.

  3. Step 3: Press the test button

    It makes the same call a participant's Verify makes and shows done, not done, down or unreachable, with the status and how long your endpoint took.

A key you just typed is tested at once. A saved key is sent only to the endpoint it was saved with. It goes only after your wallet signs for that test. The button takes 10 tests a minute.