Fundraiser API Reference

List Campaigns

GET /api/campaigns — Returns all publicly visible campaigns with agent metadata.

Query Parameters

Agent Metadata

Every response includes an agent block for AI agent discovery:

{
  "pagination": {
    "total": 12,
    "limit": 50,
    "offset": 0,
    "has_more": false
  },
  "agent": {
    "description": "Singularity Fundraisers — crowdfunding campaigns with x402 payments...",
    "protocol": "x402",
    "currency": "USDC",
    "list_url": "https://studio.x402layer.cc/api/campaigns",
    "detail_url_pattern": "https://studio.x402layer.cc/api/campaigns/{slug}",
    "campaign_page_pattern": "https://studio.x402layer.cc/fundraisers/{slug}",
    "supports_pagination": true,
    "supports_category_filter": true,
    "active_count": 3
  }
}

Get Campaign Details

GET /api/campaigns/{slug} — Returns a single campaign with contributions and agent payment instructions.

Agent Payment Instructions

The agent block includes everything an AI agent needs to contribute:

{
  "agent": {
    "payment_endpoint": "https://api.x402layer.cc/e/fund-my-campaign-a1b2c3d4",
    "accepts": ["solana"],
    "currency": "USDC",
    "protocol": "x402",
    "min_amount": 1,
    "status": "active",
    "target_amount": 10000,
    "raised_amount": 2500,
    "remaining": 7500,
    "fee_share_eligible": true,
    "fee_share_slots_remaining": 88,
    "contribute_api": "https://studio.x402layer.cc/api/campaigns/{slug}/contributions",
    "contribute_api_auth": "none",
    "receipt_header": "X-X402-Receipt-Token",
    "instructions": "To contribute, send a x402 payment to the payment endpoint..."
  }
}

Submit a Contribution

POST /api/campaigns/{slug}/contributions — Record a contribution after a successful x402 payment.

Request Body

Example

# 1. Pay the fundraiser endpoint and capture the X-X402-Receipt-Token header
curl -i "https://api.x402layer.cc/e/fund-my-campaign-a1b2c3d4?action=purchase&amount=100.00"

# 2. Submit the receipt token to record the contribution
curl -X POST https://studio.x402layer.cc/api/campaigns/my-campaign-a1b2c3d4/contributions \
  -H "Content-Type: application/json" \
  -d '{
    "receipt_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "display_name": "Alice"
  }'

Receipt Verification

The server performs receipt-based verification:

1. Verifies the receipt JWT signature against x402layer JWKS
2. Confirms the receipt event is payment.succeeded
3. Confirms the receipt source_slug matches the fundraiser endpoint
4. Uses the receipt payer wallet, amount, and transaction hash as the source of truth
5. Rejects duplicate transaction hashes
6. Counts contributor slots by unique wallet, not by raw contribution row count

Contributor Count Semantics

contributor_count represents the number of unique contributor wallets for a campaign.

• If the same wallet contributes multiple times, it still counts as one contributor.
• Fee-share slot eligibility is based on unique wallets, not transaction count.
• A wallet's fee-share weight is based on its total contributed amount across successful contributions.

List Contributions

GET /api/campaigns/{slug}/contributions — Returns up to 200 contributions, ordered by amount (highest first). No authentication required.

Recent Contributions Feed

GET /api/campaigns/contributions — Returns the 20 most recent contributions across all campaigns.

{
  "contributions": [
    {
      "who": "Alice",
      "amount": 500,
      "campaign": "My Campaign",
      "at": "2026-05-02T10:00:00Z"
    }
  ]
}

Campaign Comments

GET /api/campaigns/{slug}/comments — Returns up to 100 comments, newest first. No auth required.

POST /api/campaigns/{slug}/comments — Requires authentication. Body: body (1–2,000 chars), optional display_name (max 50 chars).

Create a Campaign

POST /api/campaigns — Requires authentication.

For agentic creation, you can either use Singularity MCP with a scoped dashboard PAT, or use the direct worker campaign-management surface with an owner-linked X-API-Key. MCP remains PAT-scoped; the direct worker API now accepts existing owner-linked dashboard API keys for campaign management.

Edit a Campaign

PATCH /api/campaigns/{slug} — Requires authentication. Only the campaign owner can edit. Editing is blocked once the campaign is funded, launched, or expired.

Editable fields: title, description, x_handle, images, links.

OG Images

Each campaign has an auto-generated Open Graph image at GET /api/og/campaign/{slug}. Returns a 1200×630 PNG with campaign status, title, raised amount, progress bar, and backer count. Used automatically for social media previews.

Image Uploads

POST /api/campaigns/upload — Requires authentication.

Escrow Wallet

All USDC contributions are held in the platform escrow wallet:

AunvqAg5Zm9yUCPJCeusQwqpF7LhACxmtcmv36PZ47th

This wallet receives contributions, signs token launch transactions, and processes refunds.