HyperbolicLabs/hyperbolic-go

HyperbolicLabs/hyperbolic-go

Description: Official Go SDK for the Hyperbolic API

Language: Go

License: Apache-2.0

Stars: 0

Forks: 0

Open issues: 1

Created: 2026-10-21T07:33:58Z

Pushed: 2026-10-28T06:33:04Z

Default branch: main

Fork: no

Archived: no

README:

hyperbolic-go

 

The official Go SDK for the Hyperbolic API. Use it to rent GPUs, manage storage volumes and SSH keys, and track your balance from Go.

The SDK is generated from Hyperbolic's published OpenAPI specification, so it covers the entire API and stays in step with it.

Requirements

• Go 1.24 or later. CI tests the two most recent Go releases.
• A Hyperbolic API key. Create one under Settings > API Keys in the dashboard.

Installation

go get github.com/HyperbolicLabs/hyperbolic-go

Usage

Quick start

This program prints your balance and the virtual machines you can rent now. Neither call spends money.

package main

import (
"context"
"fmt"
"log"
"os"

hyperbolic "github.com/HyperbolicLabs/hyperbolic-go"
)

func main() {
ctx := context.Background()
client, err := hyperbolic.NewClient(os.Getenv("HYPERBOLIC_API_KEY"))
if err != nil {
log.Fatal(err)
}

balance, err := client.Balances.Get(ctx)
if err != nil {
log.Fatal(err)
}
fmt.Printf("balance: $%.2f\n", balance.BalanceCents/100)

options, err := client.Rentals.Options(ctx)
if err != nil {
log.Fatal(err)
}
for _, o := range options {
v, err := o.ValueByDiscriminator()
if err != nil {
continue // a machine type this version of the SDK does not know
}
if vm, ok := v.(hyperbolic.VirtualMachineOption); ok && vm.Enabled {
fmt.Printf("%d x %s in %s: $%.2f/hour\n", vm.GPUCount, vm.GPUType, vm.Region, vm.CostPerHourCents/100)
}
}
}

Renting a GPU

created, err := client.Rentals.Create(ctx, hyperbolic.CreateRentalParams{
RentalType: hyperbolic.RentalTypeVirtualMachine,
GPUType: hyperbolic.Ptr(hyperbolic.GPUTypeH100),
GPUCount: 1,
Region: hyperbolic.Ptr("us-central-1"),
Label: hyperbolic.Ptr("train-run-42"),
})
if err != nil {
return err // see "Retries and create safety" before retrying
}

// The API has no webhooks: poll until the rental is running.
found, err := client.Rentals.Get(ctx, hyperbolic.GetRentalParams{RentalID: created.RentalID})
if err != nil {
return err
}
if active, err := found.AsActiveRentalLookup(); err == nil && active.Rental.Status == hyperbolic.RentalStatusRunning {
for _, ep := range active.Rental.SSHEndpoints {
fmt.Printf("ssh %s@%s -p %d\n", ep.User, ep.Host, ep.Port)
}
}

// Stop paying.
if _, err := client.Rentals.Terminate(ctx, hyperbolic.TerminateRentalParams{RentalID: created.RentalID}); err != nil {
return err
}

A rental is identified by its string RentalID. Money is in cents, including CostPerHour on a rental's current term.

Services

The client groups the API's operations into services named after the specification's tags.

| Service | Methods | |---|---| | Rentals | Options, Create, Get, ListActive, ListHistory, HasHistory, ActiveSummary, Update, Terminate, RebootInstance, AttachSSHKey, DetachSSHKey, and reservations: ReserveOptions, RequestReservation, ConversionQuote, ConvertToReserved, ExtensionQuote, ExtendReserved | | StorageVolumes | Options, List, Create, Update, Attach, Terminate | | SSHKeys | List, ListForRental, Create, Update, Delete | | Balances | Get | | APIKeys | List | | Users | Me, UpdateMe, VerifyPhoneNumber, DeleteMe |

Each method takes a context.Context and, when the operation has inputs, one ...Params struct. Its doc comment names the HTTP call it makes. Deprecated operations are left out.

Configuration

NewClient takes options.

client, err := hyperbolic.NewClient(apiKey,
hyperbolic.WithUserAgent("my-scheduler/1.4.0"),
hyperbolic.WithHTTPClient(&http.Client{Timeout: 10 * time.Second}),
hyperbolic.WithRetryPolicy(hyperbolic.NoRetries()),
)

| Option | Default | Use it to | |---|---|---| | WithBaseURL | https://api.hyperbolic.ai | Point the client at another endpoint, such as a test server. | | WithHTTPClient | An http.Client with a 30 second timeout | Set your own transport, proxy or timeout. | | WithUserAgent | hyperbolic-go/ | Name your application in the User-Agent header, ahead of the SDK's own token. | | WithRetryPolicy | DefaultRetryPolicy(), 3 attempts | Tune retries, or turn them off with NoRetries(). |

The base URL must use https, except for loopback test servers, so an API key never crosses a network unencrypted. The key never appears in %v or %#v output.

Errors

Every API failure is an *hyperbolic.APIError with the HTTP status, the machine-readable Code, the message and the Issues the API listed. Helpers cover the common checks.

| Helper | True when | |---|---| | IsOutcomeUnknown(err) | A call that is not safe to repeat may or may not have taken effect | | IsNotFound(err) | The object does not exist, including a lookup the API answered with null | | IsUnauthorized(err) | The API key was rejected | | IsRateLimited(err) | The request hit a rate limit. APIError.RetryAfter says how long to wait | | HasCode(err, hyperbolic.CodeInsufficientBalance) | The API returned that error code |

Retries and create safety

Calls that are safe to repeat are retried on 429, 502, 503, 504 and transport errors, with exponential backoff and jitter, honoring Retry-After. If the server asks to wait longer than RetryPolicy.MaxDelay, the client returns the error instead of blocking, so a controller can requeue.

Creating a rental is not idempotent, and the API has no idempotency key. A create that fails after the server applied it, through a 5xx, a timeout or a dropped connection, would rent the GPUs twice if retried blindly. The client retries such a call only on a 429 or when the connection never opened, the two cases where the server provably did not process it. Any other failure returns an error matching ErrOutcomeUnknown.

created, err :=...