Web3 Subscribe Schema

Source OpenAPI: 0xArchive API 1.6.1; 147 paths; 128 component schemas. x402-protected endpoint for purchasing 30-day Build or Pro access with USDC on Base. Unknown wallets receive an account and API key only after successful payment settlement. Existing disabled wallets are rejected before facilitator verification or settlement. Flow: 1. POST with { "tier": "build" } (no payment header) → Server returns 402 with payment details (amount, pay_to address, network) 2. Sign an EIP-712 TransferWithAuthorization (EIP-3009) on USDC Base for the specified amount 3. Build x402 v2 payment payload, base64-encode it, and retry with payment-signature header 4. Server verifies and settles payment via the facilitator → grants access → returns API key No API key required. Payment establishes paid wallet access.

Route Metadata

Field	Value
Method	`POST`
Path	`/v1/web3/subscribe`
operationId	`web3Subscribe`
Tag	Web3 Authentication
Family	Web3 Auth
Deprecated or legacy	no

Request Parameters

Header Parameters

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "web3Subscribe header parameters",
  "type": "object",
  "properties": {
    "payment-signature": {
      "description": "Base64-encoded x402 v2 payment payload containing the EIP-3009 signed USDC transfer authorization. Omit on first request to receive payment details.",
      "type": "string",
      "x-parameter-location": "header"
    }
  }
}

Request Body

application/json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "web3Subscribe request body",
  "type": "object",
  "required": [
    "tier"
  ],
  "properties": {
    "tier": {
      "description": "Subscription tier to purchase",
      "type": "string",
      "enum": [
        "build",
        "pro"
      ],
      "example": "build"
    }
  }
}

Response Contracts

Status 200

Subscription created successfully (returned when valid payment-signature header is provided)

application/json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "web3Subscribe response 200",
  "type": "object",
  "properties": {
    "api_key": {
      "description": "The generated API key for the new subscription",
      "type": "string",
      "example": "0xa_..."
    },
    "expires_at": {
      "description": "Subscription expiration date (30 days from purchase)",
      "type": "string",
      "format": "date-time"
    },
    "tier": {
      "description": "The subscription tier activated",
      "type": "string",
      "example": "build"
    },
    "tx_hash": {
      "description": "On-chain transaction hash for the USDC transfer (if settled)",
      "type": "string",
      "nullable": true
    },
    "wallet_address": {
      "description": "The wallet address associated with the subscription",
      "type": "string"
    }
  }
}

Status 402

Payment required. Response includes payment details: amount (micro-USDC), pay_to address, and network. Sign and retry with payment-signature header.

application/json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "web3Subscribe response 402",
  "type": "object",
  "properties": {
    "payment": {
      "type": "object",
      "properties": {
        "amount": {
          "description": "Amount in micro-USDC (6 decimals)",
          "type": "string",
          "example": "49000000"
        },
        "network": {
          "description": "Blockchain network",
          "type": "string",
          "example": "base"
        },
        "pay_to": {
          "description": "Treasury address to send USDC to",
          "type": "string",
          "example": "0x..."
        }
      }
    }
  }
}

Status 403

The existing wallet account is disabled. No facilitator verification or settlement is attempted.

application/json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "web3Subscribe response 403",
  "type": "object",
  "required": [
    "code",
    "error",
    "error_code",
    "request_id"
  ],
  "properties": {
    "code": {
      "type": "integer",
      "format": "int32"
    },
    "error": {
      "type": "string"
    },
    "error_code": {
      "type": "string"
    },
    "request_id": {
      "type": "string"
    }
  }
}

OpenAPI example

{
  "code": 403,
  "error": "Account is disabled",
  "error_code": "account_disabled",
  "request_id": "00000000-0000-0000-0000-000000000000"
}

Status 429

Rate limit exceeded

application/json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "web3Subscribe response 429",
  "description": "Error response",
  "type": "object",
  "properties": {
    "code": {
      "description": "HTTP status code",
      "type": "integer"
    },
    "error": {
      "description": "Error message",
      "type": "string"
    },
    "error_code": {
      "description": "Machine-readable error code. Common values: `invalid_query_params` (a query parameter failed to parse or validate) and `invalid_path_params` (a path parameter failed to parse). Other endpoint-specific codes exist; treat unknown codes as generic errors of the given HTTP status.",
      "type": "string"
    },
    "request_id": {
      "description": "Unique request ID for support",
      "type": "string",
      "format": "uuid"
    }
  }
}

OpenAPI example

{
  "code": 429,
  "error": "Rate limit exceeded"
}

API reference

SDKs & tooling

AI & agents

Web3 Subscribe Schema

Route Metadata

Request Parameters

Header Parameters

Request Body

application/json

Response Contracts

Status 200

application/json

Status 402

application/json

Status 403

application/json

OpenAPI example

Status 429

application/json

OpenAPI example

​Route Metadata

​Request Parameters

​Header Parameters

​Request Body

​application/json

​Response Contracts

​Status 200

​application/json

​Status 402

​application/json

​Status 403

​application/json

OpenAPI example

​Status 429

​application/json

OpenAPI example

Route Metadata

Request Parameters

Header Parameters

Request Body

application/json

Response Contracts

Status 200

application/json

Status 402

application/json

Status 403

application/json

Status 429

application/json