API Reference

Base URL: https://fetchquests.io/api (production) or http://localhost:3001/api (development)

Authentication

Most endpoints require a JWT token obtained via SIWE sign-in:

Authorization: Bearer {token}

---

Auth Endpoints

GET /auth/nonce

Get a nonce for SIWE signing.

Query Parameters:

• address (required) — Ethereum address

Response:

{
  "nonce": "abc123...",
  "nonceToken": "eyJ...signature"
}

---

POST /auth/verify

Verify signature and get JWT token.

Body:

{
  "address": "0x123...",
  "signature": "0xabc...",
  "nonce": "abc123...",
  "nonceToken": "eyJ...signature",
  "message": "Fetch Quests wants you to sign in..."
}

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIs..."
}

---

POST /auth/beta

Validate beta access code.

Body:

{
  "code": "BETA-ABC123"
}

Response:

{
  "valid": true
}

---

Profile Endpoints

GET /profile/

Get a user's profile (public).

Query Parameters:

• init=true (optional) — Auto-create profile if doesn't exist

Response:

{
  "address": "0x123...",
  "ensAddress": "alice.eth",
  "githubUsername": "alice",
  "profilePhoto": "photo-01",
  "farmerProfile": { ... },
  "giverProfile": { ... },
  "badges": [ ... ],
  "genesisDAO": { "isMember": true, "title": "Core Contributor" }
}

---

PUT /profile/

Update user profile. Requires auth.

Headers:

Authorization: Bearer {token}

Body: (partial update)

{
  "githubUsername": "alice",
  "ensAddress": "alice.eth"
}

Response: Updated profile object.

---

Quest Endpoints

GET /quests

List all quests (public).

Query Parameters:

• id (optional) — Get single quest by ID

Response:

[
  {
    "id": "quest-1234567890-abcd",
    "title": "Build landing page",
    "description": "...",
    "reward": "100 USDC",
    "status": "open",
    ...
  }
]

---

POST /quests

Create a new quest. Requires auth.

Body:

{
  "title": "Build landing page",
  "description": "Create a responsive landing page...",
  "reward": "100 USDC",
  "rewardAmount": 100,
  "rewardToken": "USDC",
  "skills": ["React", "Tailwind"],
  "maxFarmers": 1,
  "category": "Frontend"
}

Response: Created quest object (201).

---

PATCH /quests

Accept or update a quest. Requires auth.

Accept a quest:

{
  "questId": "quest-1234567890-abcd",
  "action": "accept"
}

Update a quest (owner only):

{
  "questId": "quest-1234567890-abcd",
  "status": "completed"
}

---

Mail Endpoints

GET /mail

Get authenticated user's mailbox. Requires auth.

Response:

[
  {
    "id": "mail-1234567890-abc",
    "from": "0x123...",
    "to": "0x456...",
    "subject": "Quest completed!",
    "body": "Great work...",
    "type": "quest",
    "sentAt": "2025-03-01T12:00:00.000Z",
    "read": false
  }
]

---

POST /mail

Send a message. Requires auth.

Body:

{
  "to": "0x456...",
  "subject": "Hello",
  "body": "Message content",
  "type": "direct"
}

---

PATCH /mail

Mark message as read. Requires auth.

Body:

{
  "messageId": "mail-1234567890-abc",
  "read": true
}

---

DELETE /mail

Delete a message. Requires auth.

Body:

{
  "messageId": "mail-1234567890-abc"
}

---

Leaderboard Endpoints

GET /leaderboard

Get leaderboard data (public).

Response:

{
  "farmers": [
    { "address": "0x...", "rank": "master", "score": 1500 }
  ],
  "givers": [ ... ],
  "guilds": [ ... ],
  "season": { "number": 1, "startDate": "...", "endDate": "..." }
}

---

Reputation Endpoints

GET /reputation

Get reputation data for an address (public).

Query Parameters:

• address (required)

Response:

{
  "address": "0x...",
  "reputation": {
    "benevolenceScore": 85,
    "reviewsReceived": [ ... ]
  },
  "farmerProfile": { ... },
  "badges": [ ... ]
}

---

Community DAO Endpoints

GET /community-dao

Get DAO data (public).

Response:

{
  "genesisCreator": { ... },
  "members": [ ... ],
  "treasury": { ... },
  "fqps": [ ... ]
}

---

POST /community-dao

Create a Fetch Quest Proposal. Requires auth.

Body:

{
  "title": "Add dark mode",
  "description": "Implement system-wide dark mode...",
  "category": "Feature Request"
}

Response: Created FQP object (201).

---

PUT /community-dao

Update DAO data. Requires auth (Genesis Creator only).

Body: (partial update)

{
  "treasury": { "balance": 5000 }
}

---

Resolve Endpoints

GET /resolve

Resolve ENS name or address.

Query Parameters:

• name — ENS name to resolve to address
• address — Address to resolve to ENS name

Response:

{
  "address": "0x123...",
  "name": "alice.eth"
}

---

GitHub Endpoints

POST /github/token

Exchange OAuth code for access token.

Body:

{
  "code": "abc123..."
}

Response:

{
  "username": "alice",
  "token": "gho_xxxx..."
}

---

Error Responses

All errors return JSON:

{
  "error": "Description of what went wrong"
}

Status	Meaning
400	Bad request (missing/invalid params)
401	Unauthorized (missing/invalid token)
403	Forbidden (not allowed)
404	Not found
405	Method not allowed
500	Internal server error