@hieco/sdk

@hieco/sdk is the core Hieco client for Hedera reads, transactions, signer-scoped actions, and server-side workflows.

It is the main application-facing SDK in the workspace. If you want one fluent API for scripts, route handlers, workers, browser signer flows, or shared domain services, start here.

Why This Package Exists

Hedera apps usually need more than raw transaction primitives. They need:

• readable domain methods
• strong typing across params and results
• a clean way to scope work to a signer
• a path from direct execution to descriptors and scheduled work
• behavior that still makes sense across browser, worker, and server runtimes

@hieco/sdk is that layer.

When To Use It

Choose @hieco/sdk when you are building:

• backend handlers and server actions
• scripts, jobs, or workers
• transaction-heavy app logic
• browser code that already has a wallet signer
• shared application services reused across runtimes

If you want React providers and query hooks, use @hieco/react.

Installation

npm install @hieco/sdk

pnpm add @hieco/sdk

yarn add @hieco/sdk

bun add @hieco/sdk

Quick Start

Server code with environment configuration

import { hieco } from "@hieco/sdk";

const client = hieco.fromEnv();
const account = await client.account.info("0.0.1001").now();

if (account.ok) {
  console.log(account.value.accountId);
}

Explicit client configuration

import { hieco } from "@hieco/sdk";

const client = hieco({
  network: "testnet",
});

const token = await client.token.info("0.0.2001").now();

Browser code with a wallet signer

import { hieco, type Signer } from "@hieco/sdk";

export function createWalletClient(signer: Signer) {
  return hieco({ network: "testnet" }).as(signer);
}

Mental Model

The SDK is built around a simple flow:

1. Create a client.
2. Enter a domain namespace such as account, token, topic, or contract.
3. Build an operation.
4. Choose how to finish it.

Most operations support more than one ending:

• .now() executes immediately
• .tx() returns a TransactionDescriptor
• .queue() creates scheduled work for later execution

That gives you one surface for both direct app code and more deliberate transaction orchestration.

Common Workflows

Run a signed transfer

import { hieco } from "@hieco/sdk";

const client = hieco.fromEnv();

const result = await client.account
  .send({
    to: "0.0.1002",
    hbar: 1,
  })
  .now();

Build now, submit later

const descriptor = client.token
  .transfer({
    tokenId: "0.0.2001",
    from: "0.0.1001",
    to: "0.0.1002",
    amount: 10,
  })
  .tx();

const receipt = await client.tx.submit(descriptor).now();

Re-exported SDK types

@hieco/sdk also re-exports common SDK-facing types so most app code can stay on one package import.

import { Mnemonic, PublicKey, type Signer, hieco } from "@hieco/sdk";

const client = hieco.forTestnet();
const publicKey = PublicKey.fromString("302a300506032b6570032100...");

Packaging Notes

The package ships browser-friendly ESM output with explicit conditional exports for browser, worker, workerd, node, and default.

For most users, the important takeaway is simple: the SDK is easier to consume in modern browser and edge-style environments without changing how you use it.

Environment Variables

hieco.fromEnv() reads these server-side environment variables:

• HIERO_NETWORK
• HIERO_OPERATOR_ID or HIERO_ACCOUNT_ID
• HIERO_PRIVATE_KEY
• HIERO_MIRROR_URL

Keep them in server-only code. Public browser configuration should use config plus an optional signer, not operator credentials.

API At A Glance

Common namespaces include:

• account
• token
• topic
• contract
• file
• schedule
• reads
• tx
• batch
• net

Core entry points:

• hieco(config?)
• hieco.fromEnv()
• hieco.forMainnet()
• hieco.forTestnet()
• hieco.forPreviewnet()
• hieco.withSigner(signer, config?)

Related Packages

• @hieco/react for React providers and hooks over this SDK
• @hieco/wallet and @hieco/wallet-react for signer-producing wallet flows
• @hieco/mirror for read-only Mirror Node access