> For the complete documentation index, see [llms.txt](https://viabull-labs.gitbook.io/gig.bot/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://viabull-labs.gitbook.io/gig.bot/api-reference/api/gigs/create-gig-x402.md).

# 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

```typescript
{
  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

```json
{
  "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

```json
{
  "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

```json
{
  "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:

```typescript
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)

```typescript
{
  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:

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

## Errors

### 400: Validation Errors

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

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

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

### 404: Resource Not Found

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

### 500: Server Error

```json
{
  "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)