API Reference

Complete HTTP API documentation for the x402 Gateway.

Base URL

https://llmogevm.opengradient.ai

Authentication Flow

The x402 protocol uses a two-step authentication flow:

1. Initial Request: Make a request without payment headers
2. Payment Response: Server responds with 402 Payment Required and payment details
3. Authenticated Request: Resubmit with signed payment in X-PAYMENT header

Endpoints

Chat Completions

Generate chat completions with conversational context.

POST /v1/chat/completions

Request Headers

Header	Required	Description
Content-Type	Yes	Must be application/json
X-PAYMENT	Conditional	Signed payment payload (required after 402 response)
X-SETTLE	No	Settlement mode: SETTLE_INDIVIDUAL, SETTLE_INDIVIDUAL_WITH_METADATA, or SETTLE_BATCH

Request Body

{
  "model": "openai/gpt-4o",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Hello!"}
  ],
  "max_tokens": 100,
  "temperature": 0.7,
  "stop": ["\n"],
  "tools": [],
  "tool_choice": "auto"
}

Field	Type	Required	Description
model	string	Yes	Model identifier (see Supported Models)
messages	array	Yes	Array of message objects
max_tokens	integer	No	Maximum tokens to generate (default: 100)
temperature	float	No	Sampling temperature 0-2 (default: 1.0)
stop	array	No	Stop sequences
tools	array	No	Tool/function definitions
tool_choice	string	No	Tool selection mode: auto, none, or specific tool

Message Object

{
  "role": "user",
  "content": "Hello!"
}

Field	Type	Description
role	string	system, user, assistant, or tool
content	string	Message content
name	string	Optional name for the participant
tool_calls	array	Tool calls made by assistant (for assistant messages)
tool_call_id	string	ID of tool call being responded to (for tool messages)

Text Completions

Generate completions from a text prompt.

POST /v1/completions

Request Body

{
  "model": "openai/gpt-4o",
  "prompt": "Translate to French: Hello, how are you?",
  "max_tokens": 100,
  "temperature": 0.7,
  "stop": ["\n"]
}

Field	Type	Required	Description
model	string	Yes	Model identifier
prompt	string	Yes	Text prompt
max_tokens	integer	No	Maximum tokens to generate
temperature	float	No	Sampling temperature 0-2
stop	array	No	Stop sequences

Payment Protocol

Step 1: Receive Payment Requirements

When you make a request without payment, the server responds with 402 Payment Required:

HTTP/1.1 402 Payment Required
Content-Type: application/json
X-PAYMENT-REQUIRED: <base64-encoded-payment-requirements>

Decode the X-PAYMENT-REQUIRED header to get payment details:

{
  "scheme": "exact",
  "network": "opengradient-10744",
  "maxAmountRequired": "1000000",
  "resource": "https://llmogevm.opengradient.ai/v1/chat/completions",
  "description": "LLM inference payment",
  "mimeType": "application/json",
  "payTo": "0x339c7de83d1a62edafbaac186382ee76584d294f",
  "maxTimeoutSeconds": 300,
  "asset": "0x...",
  "extra": {
    "name": "OUSDC",
    "version": "1"
  }
}

Step 2: Create Payment Payload

Create a payment payload matching the EIP-3009 transferWithAuthorization format:

{
  "from": "0xYourWalletAddress",
  "to": "0x339c7de83d1a62edafbaac186382ee76584d294f",
  "value": "1000000",
  "validAfter": 0,
  "validBefore": 1704067200,
  "nonce": "0x1234567890abcdef..."
}

Step 3: Sign the Payment

Sign the payment payload using EIP-712 typed data signing:

Domain:

{
  "name": "OUSDC",
  "version": "1",
  "chainId": 10744,
  "verifyingContract": "0x..."
}

Types:

{
  "TransferWithAuthorization": [
    {"name": "from", "type": "address"},
    {"name": "to", "type": "address"},
    {"name": "value", "type": "uint256"},
    {"name": "validAfter", "type": "uint256"},
    {"name": "validBefore", "type": "uint256"},
    {"name": "nonce", "type": "bytes32"}
  ]
}

Step 4: Submit Payment

Base64-encode the payment object and include it in the X-PAYMENT header:

{
  "payload": {
    "signature": "0xabcd...",
    "authorization": {
      "from": "0xYourWalletAddress",
      "to": "0x339c7de83d1a62edafbaac186382ee76584d294f",
      "value": "1000000",
      "validAfter": 0,
      "validBefore": 1704067200,
      "nonce": "0x1234567890abcdef..."
    }
  }
}

POST /v1/chat/completions
X-PAYMENT: eyJwYXlsb2FkIjp7...base64-encoded...
Content-Type: application/json

{...request body...}

Response Format

Successful Response

HTTP/1.1 200 OK
Content-Type: application/json
X-PAYMENT-RESPONSE: <base64-encoded-payment-receipt>

Chat Completion Response

{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1704067200,
  "model": "openai/gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 8,
    "total_tokens": 18
  }
}

Text Completion Response

{
  "id": "cmpl-123",
  "object": "text_completion",
  "created": 1704067200,
  "model": "openai/gpt-4o",
  "choices": [
    {
      "index": 0,
      "text": "Bonjour, comment allez-vous?",
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 8,
    "completion_tokens": 6,
    "total_tokens": 14
  }
}

Payment Receipt

Decode the X-PAYMENT-RESPONSE header to get payment settlement details:

{
  "success": true,
  "network": "opengradient-10744",
  "chainId": 10744,
  "txHash": "0x5678...",
  "payer": "0xYourWalletAddress"
}

Error Responses

402 Payment Required

Payment needed to proceed. See Payment Protocol.

400 Bad Request

{
  "error": {
    "message": "Invalid request body",
    "type": "invalid_request_error",
    "code": "invalid_request"
  }
}

401 Unauthorized

{
  "error": {
    "message": "Invalid payment signature",
    "type": "authentication_error",
    "code": "invalid_signature"
  }
}

402 Insufficient Funds

{
  "error": {
    "message": "Insufficient OUSDC balance",
    "type": "payment_error",
    "code": "insufficient_funds"
  }
}

429 Rate Limited

{
  "error": {
    "message": "Rate limit exceeded",
    "type": "rate_limit_error",
    "code": "rate_limited"
  }
}

500 Internal Error

{
  "error": {
    "message": "Internal server error",
    "type": "server_error",
    "code": "internal_error"
  }
}

Tools / Function Calling

Define tools that the model can call:

{
  "model": "openai/gpt-4o",
  "messages": [
    {"role": "user", "content": "What's the weather in San Francisco?"}
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get current weather for a location",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "City name"
            }
          },
          "required": ["location"]
        }
      }
    }
  ],
  "tool_choice": "auto"
}

When the model calls a tool, the response includes:

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_abc123",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"location\": \"San Francisco\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ]
}

Submit tool results by adding a tool message:

{
  "messages": [
    {"role": "user", "content": "What's the weather in San Francisco?"},
    {
      "role": "assistant",
      "tool_calls": [{"id": "call_abc123", "type": "function", "function": {"name": "get_weather", "arguments": "{\"location\": \"San Francisco\"}"}}]
    },
    {
      "role": "tool",
      "tool_call_id": "call_abc123",
      "content": "{\"temperature\": 65, \"condition\": \"sunny\"}"
    }
  ]
}