Marketplace API

Through the Marketplace API, you or your AI Agents can programmatically access GPU resources

Authentication

Most endpoints require a Bearer token in the Authorization header:

Authorization: Bearer $HYPERBOLIC_API_KEY

Endpoints

1. List Available Machines

Lists all available machines in the marketplace. This endpoint does not require a Bearer token in the Authorization header.

Endpoint

POST https://api.hyperbolic.xyz/v1/marketplace

Request Headers

HeaderValueRequired
Content-Typeapplication/jsonYes

Request Body

{ "filters": {} }

Example Request

curl https://api.hyperbolic.xyz/v1/marketplace -X POST \ -H "Content-type: application/json" \ -d '{"filters":{}}'

Response Format

{ "instances": [ { "id": string, // Node identifier "status": string, // e.g., "node_ready" "hardware": { "cpus": [{ "hardware_type": "cpu", "model": string, "cores": number, "virtual_cores": number }], "gpus": [{ "hardware_type": "gpu", "model": string, "clock_speed": number, "compute_power": number, "ram": number, "interface": string }], "storage": [{ "hardware_type": "storage", "capacity": number }], "ram": [{ "hardware_type": "ram", "capacity": number }] }, "instances": [{ "id": string, "status": string, "hardware": [{ "gpu": { "hardware_type": "gpu", "model": string, "ram": number } }] }], "location": { "region": string }, "network": {}, "gpus_total": number, "gpus_reserved": number, "has_persistent_storage": boolean, "supplier_id": string, "pricing": { "price": { "amount": number, "period": string, "agent": string } }, "reserved": boolean, "cluster_name": string } ] }

Important Fields

  • id: Node identifier (used as node_name in create instance)
  • cluster_name: Required for instance creation
  • gpus_total: Total GPUs available on the machine
  • gpus_reserved: Number of GPUs currently in use
  • reserved: Whether the machine is totally reserved or currently available
  • pricing.price.amount: Hourly cost in USD

Notes

  • Check reserved status and gpus_reserved vs gpus_total to determine availability
  • The status field indicates if the machine is ready for use (node_ready)
  • Each machine has different GPU configurations and pricing
  • Storage and RAM specifications are included in the hardware details

2. Create Instance

Endpoint

POST https://api.hyperbolic.xyz/v1/marketplace/instances/create

Request Headers

HeaderValueRequired
Content-Typeapplication/jsonYes
AuthorizationBearer $HYPERBOLIC_API_KEYYes

Request Body

{ "cluster_name": string, "node_name": string, "gpu_count": number, "image": { "name": string, "tag": string, "port": number } }

Example Request

curl -X POST "https://api.hyperbolic.xyz/v1/marketplace/instances/create" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $HYPERBOLIC_API_KEY" \ -d '{ "cluster_name": "extrasmall-chamomile-duck", "node_name": "prd-acl-msi-02.fen.intra", "gpu_count": 1 }'

Important Fields

  • cluster_name: Name of the cluster to create instance in
  • node_name: Name of the node (from List Available Machines endpoint)
  • gpu_count: Number of GPUs to allocate
  • image: Optional container configuration

Notes

  • The image object is optional
  • gpu_count must not exceed available GPUs on the node

3. List User Instances

Endpoint

POST https://api.hyperbolic.xyz/v1/marketplace/instances

Request Headers

HeaderValueRequired
Content-Typeapplication/jsonYes
AuthorizationBearer $HYPERBOLIC_API_KEYYes

Example Request

curl -X GET "https://api.hyperbolic.xyz/v1/marketplace/instances" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $HYPERBOLIC_API_KEY"

4. View Instance History

Endpoint

GET https://api.hyperbolic.xyz/v1/marketplace/instances/history

Request Headers

HeaderValueRequired
Content-Typeapplication/jsonYes
AuthorizationBearer $HYPERBOLIC_API_KEYYes

Example Request

curl -X GET "https://api.hyperbolic.xyz/v1/marketplace/instances/history" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $HYPERBOLIC_API_KEY"

5. Terminate Instance

Endpoint

POST https://api.hyperbolic.xyz/v1/marketplace/instances/terminate

Request Headers

HeaderValueRequired
Content-Typeapplication/jsonYes
AuthorizationBearer $HYPERBOLIC_API_KEYYes

Example Request

curl -X POST "https://api.hyperbolic.xyz/v1/marketplace/instances/create" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $HYPERBOLIC_API_KEY" \ -d '{ "id": "your-instance-id" }'

5. Query Credit Balance

Endpoint

GET https://api.hyperbolic.xyz/billing/get_current_balance

Request Headers

HeaderValueRequired
Content-Typeapplication/jsonYes
AuthorizationBearer $HYPERBOLIC_API_KEYYes

Example Request

curl -X GET "https://api.hyperbolic.xyz/billing/get_current_balance" \ -H "Authorization: Bearer $HYPERBOLIC_API_KEY" \ -H "Content-Type: application/json"

Did this page help you?