Akash SDK - API Reference

Complete API reference for the Akash SDKs.

Both SDKs are generated from the same protobuf definitions and follow similar patterns.

SDK Initialization

import { DirectSecp256k1HdWallet } from "@cosmjs/proto-signing";
import { createChainNodeSDK } from "@akashnetwork/chain-sdk";

// Initialize wallet from mnemonic
const wallet = await DirectSecp256k1HdWallet.fromMnemonic(mnemonic, { 
prefix: "akash" 
});

// Initialize SDK
const sdk = createChainNodeSDK({
query: {
  baseUrl: "https://grpc.akashnet.net:443", // gRPC endpoint
  transportOptions: {
    pingIntervalMs: 30000,
    pingTimeoutMs: 10000,
    idleConnectionTimeoutMs: 60000,
    defaultTimeoutMs: 30000
  }
},
tx: {
  baseUrl: "https://rpc.akashnet.net:443", // RPC endpoint
  signer: wallet,
  gasPrice: "0.025uakt"
}
});

// SDK exposes:
// - sdk.akash.* (Akash-specific modules)
// - sdk.cosmos.* (Cosmos SDK modules)

TypeScript Options:

  • query.baseUrl (required): gRPC endpoint URL
  • query.transportOptions (optional): Connection settings
  • tx.baseUrl (required for transactions): RPC endpoint URL
  • tx.signer (required for transactions): CosmJS wallet instance
  • tx.gasPrice (optional): Gas price (default: “0.025uakt”)

SDL Operations

import { generateManifest, generateManifestVersion, yaml, type SDLInput } from "@akashnetwork/chain-sdk";

// Define SDL using the yaml template tag
const sdl: SDLInput = yaml`
version: "2.0"
services:
web:
  image: nginx
  expose:
    - port: 80
      as: 80
      to:
        - global: true
`;

// Generate manifest and deployment groups
const result = generateManifest(sdl);

if (!result.ok) {
console.error("Validation errors:", result.value);
} else {
// Get deployment manifest (Array of groups with service definitions)
const manifest = result.value.groups;

// Get deployment groups (Array of GroupSpec for blockchain submission)
const groupSpecs = result.value.groupSpecs;

// Get SDL version hash (SHA-256)
const version = await generateManifestVersion(manifest);
}

TypeScript Functions:

  • generateManifest(sdl, networkId?) - Generate manifest and deployment groups
    • sdl: SDLInput - Parsed SDL object (use the yaml template tag)
    • networkId: “mainnet” | “testnet” | “sandbox” (default: “mainnet”)
    • Returns { ok: true, value: { groups, groupSpecs } } on success
    • Returns { ok: false, value: ValidationError[] } on validation failure
  • generateManifestVersion(manifest) - Get SHA-256 hash of manifest
    • manifest: Manifest - The groups array from generateManifest result
    • Returns Promise<Uint8Array>
  • yaml`...` - Template tag for defining SDL with interpolation support

Go Functions:

  • sdl.ReadFile(path) - Read SDL from file
  • sdl.Read([]byte) - Parse SDL from bytes
  • DeploymentGroups() - Get deployment groups
  • Manifest() - Get deployment manifest
  • Version() - Get SDL version hash

Deployment Operations

Query Deployments

// Get all deployments for owner
const result = await sdk.akash.deployment.v1beta4.getDeployments({
filters: {
  owner: "akash1...",
  state: "active" // "active" | "closed" | undefined
},
pagination: {
  limit: 100,
  offset: 0
}
});

// result.deployments: Array of deployment info
// result.pagination: Pagination info

// Get specific deployment
const deployment = await sdk.akash.deployment.v1beta4.getDeployment({
id: {
  owner: "akash1...",
  dseq: "1234567"
}
});

Create Deployment

import { generateManifest, yaml, type SDLInput } from "@akashnetwork/chain-sdk";

const sdl: SDLInput = yaml`...`; // Your SDL definition
const result = generateManifest(sdl);

if (!result.ok) {
throw new Error("SDL validation failed: " + JSON.stringify(result.value));
}

const { groupSpecs } = result.value;

// Get current block height for dseq
const status = await sdk.cosmos.base.tendermint.v1beta1.getLatestBlock({});
const dseq = status.block.header.height;

// Get account
const accounts = await wallet.getAccounts();

// Create deployment
const deployResult = await sdk.akash.deployment.v1beta4.createDeployment({
id: {
  owner: accounts[0].address,
  dseq: dseq
},
groups: groupSpecs,
deposit: {
  denom: "uakt",
  amount: "5000000" // 5 AKT
},
depositor: accounts[0].address
});

// Returns transaction result

Update Deployment

import { generateManifest, yaml, type SDLInput } from "@akashnetwork/chain-sdk";

const newSdl: SDLInput = yaml`...`; // Your updated SDL definition
const result = generateManifest(newSdl);

if (!result.ok) {
throw new Error("SDL validation failed: " + JSON.stringify(result.value));
}

const updateResult = await sdk.akash.deployment.v1beta4.updateDeployment({
id: {
  owner: accounts[0].address,
  dseq: "1234567"
},
groups: result.value.groupSpecs
});

Close Deployment

const result = await sdk.akash.deployment.v1beta4.closeDeployment({
id: {
  owner: accounts[0].address,
  dseq: "1234567"
}
});

Market Operations

Query Bids

const bids = await sdk.akash.market.v1beta5.getBids({
filters: {
  owner: "akash1...",
  dseq: "1234567",
  state: "open" // "open" | "active" | "closed"
},
pagination: {
  limit: 100
}
});

// bids.bids: Array of bid info

Create Lease (Accept Bid)

const result = await sdk.akash.market.v1beta5.createLease({
bidId: {
  owner: accounts[0].address,
  dseq: "1234567",
  gseq: 1,
  oseq: 1,
  provider: "akash1..."
}
});

Query Leases

const leases = await sdk.akash.market.v1beta5.getLeases({
filters: {
  owner: "akash1...",
  state: "active"
},
pagination: {
  limit: 100
}
});

Provider Operations

Query Providers

// Get all providers
const providers = await sdk.akash.provider.v1beta4.getProviders({
pagination: {
  limit: 100
}
});

// Get specific provider
const provider = await sdk.akash.provider.v1beta4.getProvider({
owner: "akash1..."
});

Provider Status (Provider API)

import { createProviderSDK } from "@akashnetwork/chain-sdk";

const providerSdk = createProviderSDK({
baseUrl: "https://provider.example.com:8444"
});

// Get provider status
const status = await providerSdk.akash.provider.v1.getStatus();

// status.clusterPublicHostname: string
// status.availableResources: Resource info
// status.pendingResources: Resource info
// status.leasedResources: Resource info

Certificate Operations

Query Certificates

const certs = await sdk.akash.cert.v1.getCertificates({
filter: {
  owner: "akash1...",
  state: "valid"
},
pagination: {
  limit: 100
}
});

Create Certificate

import { certificateManager } from "@akashnetwork/chain-sdk";

const accounts = await wallet.getAccounts();

// Generate certificate pair
const certPair = await certificateManager.generatePEM(accounts[0].address);

// Publish to blockchain
const result = await sdk.akash.cert.v1.createCertificate({
owner: accounts[0].address,
cert: Buffer.from(certPair.cert, 'utf-8'),
pubkey: Buffer.from(certPair.publicKey, 'utf-8')
});

// Save certPair.cert and certPair.privateKey for later use

Revoke Certificate

const result = await sdk.akash.cert.v1.revokeCertificate({
id: {
  owner: accounts[0].address,
  serial: "certificate-serial-number"
}
});

Cosmos SDK Operations

Query Account Balance

// Get balance for specific denom
const balance = await sdk.cosmos.bank.v1beta1.getBalance({
address: "akash1...",
denom: "uakt"
});

// balance.balance.amount: string (in uakt)
// Convert to AKT: parseInt(balance.balance.amount) / 1000000

// Get all balances
const allBalances = await sdk.cosmos.bank.v1beta1.getAllBalances({
address: "akash1...",
pagination: {
  limit: 100
}
});

Send Tokens

const result = await sdk.cosmos.bank.v1beta1.send({
fromAddress: accounts[0].address,
toAddress: "akash1...",
amount: [{
  denom: "uakt",
  amount: "1000000" // 1 AKT
}]
});

Query Block Info

// Get latest block
const latest = await sdk.cosmos.base.tendermint.v1beta1.getLatestBlock({});

// latest.block.header.height: string
// latest.block.header.time: timestamp

// Get block by height
const block = await sdk.cosmos.base.tendermint.v1beta1.getBlockByHeight({
height: "1234567"
});

Authentication

JWT Token

import { Secp256k1HdWallet } from "@cosmjs/amino";
import { JwtTokenManager } from "@akashnetwork/chain-sdk";

const wallet = await Secp256k1HdWallet.fromMnemonic(mnemonic, { 
prefix: "akash" 
});
const accounts = await wallet.getAccounts();

// Initialize token manager
const tokenManager = new JwtTokenManager(wallet);

// Generate JWT token
const token = await tokenManager.generateToken({
iss: accounts[0].address,
exp: Math.floor(Date.now() / 1000) + 3600, // 1 hour
iat: Math.floor(Date.now() / 1000),
version: "v1",
leases: { access: "full" }
});

// Use token for provider API requests
const response = await fetch(
`https://provider.example.com:8443/lease/${dseq}/1/1/status`,
{
  headers: {
    Authorization: `Bearer ${token}`
  }
}
);

JWT Token Claims:

  • iss (required): Issuer address (your Akash address)
  • exp (required): Expiration timestamp (Unix time)
  • iat (required): Issued at timestamp (Unix time)
  • nbf (required): Not before timestamp (Unix time)
  • version (required): Token version (“v1”)
  • leases (required): Lease access permissions

Access Types:

  • full - Full access to all leases (TypeScript: { access: "full" }, Go: AccessTypeFull)
  • scoped - Scoped access with specific permissions (Go: AccessTypeScoped)
  • granular - Granular access per deployment (Go: AccessTypeGranular)

Error Handling

import { TxError } from "@akashnetwork/chain-sdk";

try {
const result = await sdk.akash.deployment.v1beta4.createDeployment({...});
} catch (error) {
if (error instanceof TxError) {
  console.error("Transaction failed:", error.message);
  console.error("Code:", error.code);
  console.error("Codespace:", error.codespace);
} else {
  console.error("Unknown error:", error);
}
}

Type Definitions

// Deployment ID
interface DeploymentID {
owner: string;
dseq: string;
}

// Bid ID
interface BidID {
owner: string;
dseq: string;
gseq: number;
oseq: number;
provider: string;
}

// Coin
interface Coin {
denom: string;
amount: string;
}

// Pagination
interface PageRequest {
key?: Uint8Array;
offset?: number;
limit?: number;
countTotal?: boolean;
reverse?: boolean;
}
Edit page on github
Examples Providers API