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"
}| Field | What it is |
|---|---|
userId | The participant's wallet, in lowercase. |
accounts.wallet | The same wallet. It is the only thing about the participant we send. |
communityId, subdomain | Your partner slug, in both. |
questId | The task's id. It stays the same once the campaign starts. |
requestId | A new UUID for each call. |
blockchain, chainId | The chain you picked in the task. The wallet is the same address on every chain. |
campaignId | The campaign's code. |
| blockchain | chainId |
|---|---|
| base | 8453 |
| robinhood | 4663 |
| ethereum | 1 |
| optimism | 10 |
| arbitrum | 42161 |
| polygon | 137 |
| bsc | 56 |
| Header | When |
|---|---|
content-type: application/json | Always. |
user-agent: GiftedStock-Tasks/1 (+https://www.giftedstock.com) | Always. |
x-api-key | When you saved an API key in the task. |
x-giftedstock-timestamp, x-giftedstock-signature | When you saved a key: see Signed calls. |
accounts.twitter is never sent, also for tasks saved before with the wallet and X.Your answer
| You answer | What the participant sees |
|---|---|
| 200 | Done. A body is optional. |
400 with { "message": "…" } | Not done, with your message. Without one: "not done yet". |
| Anything else or nothing within 10 seconds | Your 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
Step 1: Fill in the task
The endpoint, your API key (optional) and the blockchain.
Step 2: Pick a test wallet
Any address. Leave it empty to use the wallet you are signed in with.
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.