Create Gig with X402 Payment

Creates a new gig with X402 payment integration. This endpoint implements the X402 payment standard for seamless token payments. The gig will be created and automatically started after successful payment.

X402 Payment Flow

IMPORTANT: This endpoint uses X402 payment authentication. The payment flow works as follows:

1. First Call: Returns 402 status with payment details

2. Payment: User completes payment through X402

3. Second Call: Gig is created and started automatically

Authentication

This endpoint uses X402 payment authentication instead of API keys. The payment header is automatically handled by the X402 middleware.

Endpoint

POST https://gigbot.xyz/api/gigs/create/x402

Input Parameters

{
  chain: "base",                               // Currently only Base network supported
  token_address: string,                       // ERC20 token contract address (only USDC supported)
  amount: number,                              // Reward amount in tokens (e.g., 11) - commission is added on top
  start_time: string,                          // ISO datetime (e.g., "2025-10-01T15:00:00Z")
  duration: "1day" | "3days",                 // Only 1day and 3days supported for X402
  gig_type: "mention" | "like" | "recast" | "boost" | "custom_bounty" | "follow" | "hold_erc20" | "buy_erc20",
  platform?: "farcaster" | "x" | "onchain",   // Optional - defaults to "farcaster"
  url?: string,                                // Required for like, recast, boost, follow tasks
  how_to_earn?: string,                        // Required for custom_bounty, optional for others
  earning_criteria?: string,                   // Optional - will use default if not provided
  keyword?: string,                            // Optional - for mention gigs (defaults to token symbol)
  token_contract?: string,                     // Required for hold_erc20 and buy_erc20 gigs
  token_amount_needed?: number,                // Required for hold_erc20 and buy_erc20 gigs
  verifier?: string                            // Optional - custom verifier for the gig
}

Examples

Custom Bounty Gig

{
  "token_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "amount": 11,
  "gig_type": "custom_bounty",
  "platform": "farcaster",
  "url": "https://farcaster.xyz/miniapps/3FMRmta8BM3P/gigbot/gigs/3200",
  "start_time": "2025-10-01T15:00:00Z",
  "duration": "3days",
  "how_to_earn": "custom_how_to_earn",
  "earning_criteria": "custom_earning_criteria"
}

Follow Gig

{
  "token_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "amount": 11,
  "gig_type": "follow",
  "platform": "farcaster",
  "url": "https://farcaster.xyz/gigbot.eth",
  "start_time": "2025-10-01T15:00:00Z",
  "duration": "1week"
}

Hold ERC20 Token Gig

{
  "token_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "amount": 11,
  "gig_type": "hold_erc20",
  "platform": "onchain",
  "token_contract": "0x4ed4E862860beD51a9570b96d89aF5E1B0Efefed",
  "token_amount_needed": 100,
  "start_time": "2025-10-01T15:00:00Z",
  "duration": "1week"
}

Buyer Example Script

As a buyer, you can call the X402 endpoint like this:

import { wrapFetchWithPayment, decodeXPaymentResponse } from 'x402-fetch';
import { privateKeyToAccount } from 'viem/accounts';

// Your private key (keep secure!)
const privKey = process.env.PRIVATE_KEY;
const account = privateKeyToAccount(privKey as `0x${string}`);

// Wrap fetch with X402 payment
const fetchWithPayment = wrapFetchWithPayment(
  fetch,
  account,
  BigInt('100000000000000000000000'), // Maximum spendable amount
);

// Call the X402 endpoint
const response = await fetchWithPayment(
  'https://gigbot.xyz/api/gigs/create/x402',
  {
    method: 'POST',
    body: JSON.stringify({
      token_address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', // USDC
      amount: 11, // Amount of tokens to distribute
      gig_type: 'custom_bounty', // Type of gig
      platform: 'farcaster', // Platform where rewards will be distributed
      url: 'https://farcaster.xyz/miniapps/3FMRmta8BM3P/gigbot/gigs/3200', // Deeplink
      start_time: '2025-10-01T15:00:00Z', // Start time in ISO 8601 format
      duration: '3days', // Duration of the gig
      how_to_earn: 'custom_how_to_earn', // Instructions on how to earn
      earning_criteria: 'custom_earning_criteria', // Criteria required to earn
    }),
  },
);

const json = await response.json();
const xPaymentHeader = response.headers.get('x-payment-response');
const decoded = xPaymentHeader ? decodeXPaymentResponse(xPaymentHeader) : null;

console.log('Response:', json);
console.log('Payment info:', decoded);

Success Response (200)

{
  message: "✅ Access granted after payment",
  gig_id: number                    // Unique identifier for the created gig
}

X402 Payment Response (402)

When payment is required, the endpoint returns a 402 status with X402 payment details:

{
  // X402 payment response structure
  // This is handled automatically by the X402 middleware
}

Errors

400: Validation Errors

{
  "error": "Invalid token address only $USDC is supported address: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
}

{
  "error": "Insufficient asset value. Minimum amount is 10 $USDC"
}

{
  "error": "Validation failed",
  "details": [
    {
      "path": "chain",
      "message": "Invalid chain. Currently only \"base\" network is supported."
    }
  ]
}

404: Resource Not Found

{
  "error": "Gig type not found available gigs: mention, like, recast, boost, custom_bounty, follow, hold_erc20, buy_erc20"
}

500: Server Error

{
  "error": "Failed to create gig"
}

Important Notes

Supported Token

• Only USDC is supported: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913

• Minimum value: $10 USD (commission is added on top, so you pay $11 total for $10 reward)

X402 Integration

• Uses X402 payment middleware for seamless token payments

• Automatically creates a wallet for the gig

• Payment is required before gig creation

• Gig is automatically started after successful payment

Commission Structure

• Platform fee: 10% commission on top of the reward amount

• Example: If you want to distribute $10, you pay $11 total ($10 reward + $1 commission)

Gig Types

• mention: Users mention a keyword in their posts

• like: Users like a specific post

• recast: Users recast a specific post

• boost: Users boost a specific post

• custom_bounty: Custom task with custom instructions

• follow: Users follow a specific account

• hold_erc20: Users hold a specific amount of ERC20 tokens

• buy_erc20: Users buy a specific amount of ERC20 tokens

Platform Support

• farcaster: Farcaster platform

• x: X/Twitter platform

• onchain: On-chain activities (for hold_erc20 and buy_erc20)

URL Format Requirements

• Farcaster: https://farcaster.xyz/{username}/0x{hash} or https://farcaster.xyz/{username}

• X/Twitter: https://twitter.com/{username}/status/{tweet_id}

• Custom: Any valid URL for custom_bounty gigs

Duration Options

• 1day: 24 hours (quick promotions)

• 3days: 72 hours (weekend events)