HyperbolicLabs/hyperbolic-x402

HyperbolicLabs/hyperbolic-x402

Description: Hyperbolic Coinbase x402 Chat Completions API

Language: TypeScript

Stars: 7

Forks: 2

Open issues: 1

Created: 2025-07-23T22:47:07Z

Pushed: 2025-09-12T23:14:40Z

Default branch: main

Fork: no

Archived: no

README:

Hyperbolic x Coinbase x402 Inference API

What is x402?

x402 is an open payment standard that enables services to charge for access to their APIs and content directly over HTTP using the 402 Payment Required status code. It allows clients to programmatically pay for resources without accounts, sessions, or credential management, using crypto-native payments for speed, privacy, and efficiency.

For more detailed information about x402, visit the official documentation.

Implementation Overview

This integration demonstrates how to interact with the Hyperbolic API using x402 payments. The implementation uses the x402-fetch library to handle payment flows transparently, allowing you to access any model available on the Hyperbolic Models page.

API Endpoint

The integration targets the Hyperbolic x402 chat completions endpoint:

POST https://hyperbolic-x402.vercel.app/v1/chat/completions

Request Parameters

Headers

| Header | Required | Description | | -------------- | -------- | ---------------------------------------- | | Content-Type | Yes | Must be application/json | | Accept | Yes | Must be application/json | | X-Request-ID | Yes | Unique identifier for the request (UUID) |

Request Body

The request body follows the OpenAI-compatible chat completions format:

| Parameter | Type | Required | Description | | ------------- | ------- | -------- | ------------------------------------------------------------- | | model | string | Yes | The model to use (e.g., "meta-llama/Llama-3.2-3B-Instruct") | | messages | array | Yes | Array of message objects with role and content | | max_tokens | number | No | Maximum number of tokens to generate (default: 512) | | temperature | number | No | Controls randomness (0.0 to 2.0, default: 0.1) | | top_p | number | No | Nuclear sampling parameter (default: 0.9) | | stream | boolean | No | Whether to stream responses (default: false) |

Example Request Body

{
"model": "meta-llama/Llama-3.2-3B-Instruct",
"messages": [
{ "role": "user", "content": "What is 1+1?" }
],
"max_tokens": 512,
"temperature": 0.1,
"top_p": 0.9,
"stream": false
}

Environment Setup

Before running the client, you'll need to set up your environment:

1. Create a .env file with your Ethereum private key:

PRIVATE_KEY=0x...

2. Install dependencies:

pnpm install

Payment Flow

The x402 payment flow works as follows:

1. Client makes a request to the API endpoint 2. If payment is required, the server responds with 402 Payment Required and payment instructions 3. The x402-fetch wrapper automatically handles the payment using your private key 4. Upon successful payment verification, the server processes your request and returns the model response 5. Transaction details are logged for confirmation

Example Implementation

You can see a complete working example in the `client.ts` file in our official repository. The example demonstrates:

• Setting up the x402-enabled fetch wrapper
• Making a chat completion request
• Handling payment responses
• Logging transaction confirmations

To run the example:

pnpm run client

Response Format

Successful responses follow the OpenAI-compatible format and include:

• The model's completion response
• Usage statistics (token counts)
• Payment confirmation details in the x-payment-response header