hcloud

TypeScript SDK and CLI for Herodotus Cloud.

This package gives you a single entrypoint to every Herodotus Cloud service. Each service is reached through its own namespace on HcloudClient.

Today the package ships:

• client.atlantic.* — Atlantic proving service (queries, buckets, x402 payments).
• client.auth.* — programmatic wallet authentication (EIP-712 → bearer session → API key).

Installation

bun add @herodotus_dev/hcloud

npm install @herodotus_dev/hcloud

Install the CLI globally:

npm install -g @herodotus_dev/hcloud

Two ways to authenticate

You can either pass an API key directly, or have the SDK obtain one through the programmatic wallet auth flow. Either path produces the same client.atlantic.* behavior; pick whichever fits your environment.

Wallet auth (no manual API key)

import { HcloudClient, privateKeySigner } from '@herodotus_dev/hcloud';

const client = new HcloudClient();

await client.auth.login({
  signer: privateKeySigner(process.env.WALLET_PRIVATE_KEY as `0x${string}`),
});

const health = await client.atlantic.healthCheck();

client.auth.login runs the full EIP-712 challenge → bearer session → API key flow against auth-billing and writes the result to disk. Subsequent runs from any process on the same machine pick the key up automatically — no re-login required to keep using Atlantic.

Explicit API key

import { HcloudClient } from '@herodotus_dev/hcloud';

const client = new HcloudClient({
  apiKey: process.env.HCLOUD_API_KEY,
});

Explicit keys win over env vars and persisted credentials. HCLOUD_API_KEY (alias: ATLANTIC_API_KEY) is read automatically when no explicit key is passed.

SDK quickstart

import { HcloudClient, submitAndWait } from '@herodotus_dev/hcloud';

const client = new HcloudClient({
  apiKey: process.env.HCLOUD_API_KEY,
});

const result = await submitAndWait(client.atlantic, {
  declaredJobSize: 'S',
  pieFile: './pie.zip',
});

console.log(result.atlanticQuery.id, result.atlanticQuery.status);

Direct API usage

import { HcloudClient } from '@herodotus_dev/hcloud';

const client = new HcloudClient({
  apiKey: process.env.HCLOUD_API_KEY,
});

const submitted = await client.atlantic.submitQuery({
  declaredJobSize: 'S',
  pieFile: './pie.zip',
  layout: 'dynamic',
});

const details = await client.atlantic.getQuery(submitted.atlanticQueryId);

console.log(details.atlanticQuery.status, details.metadataUrls);

CLI quickstart

# One-time wallet auth (writes ~/.hcloud/credentials.json)
WALLET_PRIVATE_KEY=0x... hcloud auth login

# After that, Atlantic commands just work:
hcloud atlantic submit-query --pie-file ./pie.zip --declared-job-size S

You can skip the wallet auth and pass an API key directly:

HCLOUD_API_KEY=... hcloud atlantic submit-query --pie-file ./pie.zip --declared-job-size S

CLI structure is hcloud <service> <command>. List service groups with hcloud --help, list commands with hcloud <service> --help. Every CLI command prints JSON so agents and shell scripts can chain outputs without scraping prose.

Common Atlantic commands:

hcloud atlantic get-query-details <query-id>
hcloud atlantic get-my-queries --limit 20 --offset 0
hcloud atlantic retry-if-retriable <query-id>
hcloud atlantic list-buckets
hcloud atlantic create-bucket --aggregator-version STONE
hcloud atlantic close-bucket <bucket-id>

Common auth commands:

hcloud auth login --private-key 0x...        # or set WALLET_PRIVATE_KEY
hcloud auth whoami                            # masks api key by default
hcloud auth list                              # all stored wallets
hcloud auth use 0xabc...                      # switch active wallet
hcloud auth api-keys list
hcloud auth api-keys create --type-name agent --type-color "#0a0"
hcloud auth refresh                           # rotate bearer pair
hcloud auth logout --all                      # wipe credentials

Atlantic SDK reference

Service surface

Reached as client.atlantic on HcloudClient.

• healthCheck(): Checks whether Atlantic is reachable. Returns { alive }.
• submitQuery(input, options): Submits a proving query. Accepts program/input/PIE/proof files, Cairo options, result target, declared job size, dedup/external IDs, and bucket fields. Returns the durable atlanticQueryId and optional x402 settlement data.
• getQuery(atlanticQueryId): Fetches query details plus metadata URLs.
• getQueryByDedupId(dedupId): Fetches a query by dedup ID. Use API-key flow; anonymous x402 does not support dedup IDs.
• listQueries({ limit, offset }): Lists submitted queries with pagination.
• getQueryStats(): Fetches query statistics for the configured API key.
• getQueryJobs(atlanticQueryId): Fetches job lifecycle details for a query.
• retryQuery(atlanticQueryId): Requests an API retry for a failed query.
• listBuckets({ limit, offset }): Lists Applicative Recursion buckets.
• createBucket(input): Creates an Applicative Recursion bucket.
• getBucket(bucketId): Fetches a bucket and associated queries.
• closeBucket(bucketId): Closes a bucket.

Workflow helpers

Free functions that take client.atlantic and compose lifecycle behavior.

• submitAndReturnId(service, input): Submit and return the query ID immediately.
• waitForQuery(service, atlanticQueryId, options): Poll until terminal status or timeout. Returns observed statuses and final query details.
• submitAndWait(service, input, options): Submit and wait in one helper while preserving the original submit result.
• retryIfRetriable(service, atlanticQueryId): Fetches current query details and retries only when the query is failed and retriable.
• getQueryWithJobs(service, atlanticQueryId): Fetches query details and query jobs together.
• submitToBucket(service, input): Submits a query into an existing bucket with explicit job index.
• createBucketAndSubmit(service, input): Creates a bucket and submits indexed queries into it.

x402

The Atlantic service supports Atlantic's x402 flow through a caller-provided payment adapter. It waits for a real 402 challenge, signs the server-provided payment requirement, retries the original submit request with PAYMENT-SIGNATURE, and parses PAYMENT-RESPONSE.

Private-key adapter

For server-side scripts, CI, or agents with a dedicated payment key, use the built-in private-key adapter:

import { HcloudClient, createPrivateKeyPaymentAdapter } from '@herodotus_dev/hcloud';

const paymentAdapter = createPrivateKeyPaymentAdapter({
  privateKey: process.env.WALLET_PRIVATE_KEY as `0x${string}`,
});

const client = new HcloudClient({
  apiKey: process.env.HCLOUD_API_KEY,
  paymentAdapter,
});

const result = await client.atlantic.submitQuery({
  declaredJobSize: 'S',
  pieFile: './pie.zip',
});

console.log(result.atlanticQueryId, result.payment);

The adapter reads the x402 requirement returned by Atlantic, verifies that accepts[].network is Base mainnet (eip155:8453) and accepts[].extra.name is USD Coin, signs an EIP-3009 transferWithAuthorization, and returns the PAYMENT-SIGNATURE payload.

Custom wallet adapter

Use a custom adapter when signing should happen through another wallet, custody service, browser wallet, or agent wallet.

import { HcloudClient, type X402PaymentAdapter, type X402PaymentPayload } from '@herodotus_dev/hcloud';

const paymentAdapter: X402PaymentAdapter = {
  async createPayment({ requirement }): Promise<X402PaymentPayload> {
    const authorization = {
      from: '0xYourWallet',
      to: requirement.payTo,
      value: requirement.amount,
      validAfter: '0',
      validBefore: String(Math.floor(Date.now() / 1000) + (requirement.maxTimeoutSeconds ?? 300)),
      nonce: '0x...32-bytes',
    };

    const signature = await signTransferWithAuthorization({
      requirement,
      authorization,
    });

    return {
      x402Version: 2,
      accepted: requirement,
      payload: {
        signature,
        authorization,
      },
    };
  },
};

const client = new HcloudClient({ paymentAdapter });

Preserve the requirement object from accepts[] verbatim. Atlantic currently accepts USD Coin on Base mainnet; do not hardcode payTo, asset, network, or amount, because Atlantic may rotate the receiver or change the required payment amount.