### Install Dependencies

Source: https://github.com/ar-io/ar-io-sdk/blob/main/examples/webpack/README.md

Run this command to install project dependencies.

```bash
yarn
```

--------------------------------

### Start Development Server

Source: https://github.com/ar-io/ar-io-sdk/blob/main/examples/webpack/README.md

Run this command to start the local development server.

```bash
yarn start
```

--------------------------------

### Install @ar.io/sdk with npm

Source: https://github.com/ar-io/ar-io-sdk/blob/main/README.md

Install the SDK using npm. Requires Node.js version 18.0.0 or higher.

```shell
npm install @ar.io/sdk
```

--------------------------------

### Install @ar.io/sdk with yarn

Source: https://github.com/ar-io/ar-io-sdk/blob/main/README.md

Install the SDK using yarn. Requires Node.js version 18.0.0 or higher.

```shell
yarn add @ar.io/sdk
```

--------------------------------

### Install AR.IO CLI with npm

Source: https://github.com/ar-io/ar-io-sdk/blob/main/CLI.md

Install the AR.IO CLI globally using npm. This command makes the CLI available system-wide.

```bash
npm install -g @ar.io/sdk
```

--------------------------------

### Install AR.IO CLI with yarn

Source: https://github.com/ar-io/ar-io-sdk/blob/main/CLI.md

Install the AR.IO CLI globally using yarn. This command makes the CLI available system-wide.

```bash
yarn global add @ar.io/sdk
```

--------------------------------

### Verify AR.IO CLI Installation

Source: https://github.com/ar-io/ar-io-sdk/blob/main/CLI.md

Check if the AR.IO CLI has been installed successfully by running this command.

```bash
ar.io --version
```

--------------------------------

### Example output for getArNSRecords

Source: https://github.com/ar-io/ar-io-sdk/blob/main/README.md

Example JSON output when retrieving a list of ArNS records, including pagination details.

```json
{
  "items": [
    {
      "name": "ao",
      "processId": "eNey-H9RB9uCdoJUvPULb35qhZVXZcEXv8xds4aHhkQ",
      "purchasePrice": 75541282285,
      "startTimestamp": 1720720621424,
      "endTimestamp": 1752256702026,
      "type": "permabuy",
      "undernameLimit": 10
    },
    {
      "name": "ardrive",
      "processId": "bh9l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM",
      "endTimestamp": 1720720819969,
      "startTimestamp": 1720720620813,
      "purchasePrice": 75541282285,
      "type": "lease",
      "undernameLimit": 100
    },
    {
      "name": "arweave",
      "processId": "bh9l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM",
      "endTimestamp": 1720720819969,
      "startTimestamp": 1720720620800,
      "purchasePrice": 75541282285,
      "type": "lease",
      "undernameLimit": 100
    },
    {
      "name": "ar-io",
      "processId": "bh9l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM",
      "endTimestamp": 1720720819969,
      "startTimestamp": 1720720619000,
      "purchasePrice": 75541282285,
      "type": "lease",
      "undernameLimit": 100
    },
    {
      "name": "fwd",
      "processId": "bh9l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM",
      "endTimestamp": 1720720819969,
      "startTimestamp": 1720720220811,
      "purchasePrice": 75541282285,
      "type": "lease",
      "undernameLimit": 100
    }
    // ...95 other records
  ],
  "hasMore": true,
  "nextCursor": "fwdresearch",
  "totalItems": 21740,
  "sortBy": "startTimestamp",
  "sortOrder": "desc"
}

```

--------------------------------

### Example output for getArNSRecord

Source: https://github.com/ar-io/ar-io-sdk/blob/main/README.md

Example JSON output when retrieving a single ArNS record.

```json
{
  "processId": "bh9l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM",
  "startTimestamp": 1720720819969,
  "endTimestamp": 1752256702026,
  "type": "lease",
  "undernameLimit": 100,
  "purchasePrice": 75541282285
}

```

--------------------------------

### Quick Start: Initialize ARIO Client

Source: https://github.com/ar-io/ar-io-sdk/blob/main/README.md

Initialize the ARIO client with a Solana RPC endpoint and fetch gateways. This is a read-only operation.

```typescript
import { ARIO } from '@ar.io/sdk';
import { createSolanaRpc } from '@solana/kit';

const rpc = createSolanaRpc('https://api.mainnet-beta.solana.com');
const ario = ARIO.init({ rpc });
const gateways = await ario.getGateways();
```

--------------------------------

### Check Node.js Version

Source: https://github.com/ar-io/ar-io-sdk/blob/main/CLI.md

Verify if Node.js is installed on your system. Ensure Node.js version is >= 18.

```bash
node --version
```

--------------------------------

### Quick Start: Buy Record with Signer

Source: https://github.com/ar-io/ar-io-sdk/blob/main/README.md

Perform a write operation, such as buying a record, which requires a Solana signer and RPC subscriptions client. Ensure your keypair.json file is correctly configured.

```typescript
import { ARIO } from '@ar.io/sdk';
import {
  createSolanaRpc,
  createSolanaRpcSubscriptions,
  createKeyPairSignerFromBytes,
} from '@solana/kit';
import { readFileSync } from 'node:fs';

const rpc = createSolanaRpc('https://api.mainnet-beta.solana.com');
const rpcSubscriptions = createSolanaRpcSubscriptions(
  'wss://api.mainnet-beta.solana.com',
);
const signer = await createKeyPairSignerFromBytes(
  new Uint8Array(JSON.parse(readFileSync('keypair.json', 'utf8'))),
);

const ario = ARIO.init({ rpc, rpcSubscriptions, signer });
await ario.buyRecord({
  name: 'foo',
  type: 'lease',
  years: 1,
  processId: '<ANT mint pubkey>',
});
```

--------------------------------

### Get Help for a Specific AR.IO CLI Command

Source: https://github.com/ar-io/ar-io-sdk/blob/main/CLI.md

Obtain detailed help information for a particular AR.IO CLI command.

```bash
ar.io help <command>
```

--------------------------------

### Example Gateway Data Output

Source: https://github.com/ar-io/ar-io-sdk/blob/main/README.md

This JSON structure represents the output when fetching gateway information. It includes details about the gateway's addresses, stake, settings, and performance statistics.

```json
{
  "items": [
    {
      "gatewayAddress": "QGWqtJdLLgm2ehFWiiPzMaoFLD50CnGuzZIPEdoDRGQ",
      "observerAddress": "IPdwa3Mb_9pDD8c2IaJx6aad51Ss-_TfStVwBuhtXMs",
      "operatorStake": 250000000000,
      "totalDelegatedStake": 0,
      "settings": {
        "allowDelegatedStaking": true,
        "allowedDelegates": [],
        "autoStake": false,
        "delegateRewardShareRatio": 10,
        "minDelegatedStake": 100000000,
        "fqdn": "ar-io.dev",
        "label": "ar.io Test",
        "note": "Test Gateway operated by PDS for the ar.io ecosystem.",
        "port": 443,
        "properties": "raJgvbFU-YAnku-WsupIdbTsqqGLQiYpGzoqk9SCVgY",
        "protocol": "https"
      },
      "startTimestamp": 1720720621424,
      "endTimestamp": 0,
      "stats": {
        "passedConsecutiveEpochs": 30,
        "failedConsecutiveEpochs": 0,
        "totalEpochCount": 31,
        "passedEpochCount": 30,
        "failedEpochCount": 1,
        "observedEpochCount": 30,
        "prescribedEpochCount": 31
      },
      "status": "joined",
      "weights": {
        "stakeWeight": 5.02400000024,
        "tenureWeight": 0.19444444444444,
        "gatewayPerformanceRatio": 1,
        "observerPerformanceRatio": 1,
        "gatewayRewardRatioWeight": 1,
        "observerRewardRatioWeight": 1,
        "compositeWeight": 0.97688888893556,
        "normalizedCompositeWeight": 0.19247316211083
      }
    }
  ],
  "hasMore": true,
  "nextCursor": "-4xgjroXENKYhTWqrBo57HQwvDL51mMdfsdsxJy6Y2Z_sA",
  "totalItems": 316,
  "limit": 100,
  "sortBy": "startTimestamp",
  "sortOrder": "desc"
}
```

--------------------------------

### Update Gateway Settings

Source: https://github.com/ar-io/ar-io-sdk/blob/main/README.md

Modifies gateway settings. Requires a signer for transaction signing. This example demonstrates updating the minimum delegated stake.

```typescript
const ario = ARIO.init({ rpc, rpcSubscriptions, signer });
const { id: txId } = await ario.updateGatewaySettings(
  {
    // any other settings you want to update
    minDelegatedStake: new ARIOToken(100).toMARIO(),
  },
  // optional additional tags
  { tags: [{ name: "App-Name", value: "My-Awesome-App" }] },
);
```

--------------------------------

### Faucet Operations

Source: https://github.com/ar-io/ar-io-sdk/blob/main/README.md

Interact with the AR.IO faucet service to obtain test tokens. This includes getting a captcha URL, claiming tokens with an authentication token, and verifying the validity of an authentication token.

```APIDOC
## Faucet

### Description
The SDK provides a wrapper for the AR.IO faucet service, allowing users to claim test tokens. This service is intended for development and testing purposes.

### Methods

#### `createFaucet({ arioInstance, processId })`
Initializes the faucet service wrapper.

*   **arioInstance** (ARIO) - Required - The initialized AR.IO SDK instance.
*   **processId** (string) - Required - A unique identifier for the current process or session.

#### `captchaUrl()`
Retrieves the URL for the captcha challenge.

*   **Returns**: `{ captchaUrl: string }` - The URL to display the captcha.

#### `claimWithAuthToken({ authToken, recipient, quantity })`
Claims tokens using a provided authentication token.

*   **authToken** (string) - Required - The authentication token obtained after solving the captcha.
*   **recipient** (string) - Required - The Solana address to receive the tokens.
*   **quantity** (number) - Required - The number of tokens to claim.
*   **Returns**: `{ id: string }` - The transaction ID of the token claim.

#### `verifyAuthToken({ authToken })`
Verifies if the provided authentication token is still valid.

*   **authToken** (string) - Required - The authentication token to verify.
*   **Returns**: `boolean` - True if the token is valid, false otherwise.

### Request Example (Claiming Tokens)
```typescript
import { ARIO } from "@ar.io/sdk";

// Assuming 'rpc' is an initialized Solana RPC client
const ario = ARIO.init({ rpc });

// Get captcha URL
const captchaUrlResponse = await ario.faucet.captchaUrl();
const captchaUrl = captchaUrlResponse.captchaUrl;

// Open captcha in a new window and listen for the auth token
const captchaWindow = window.open(captchaUrl, "_blank", "width=600,height=600");

window.parent.addEventListener("message", async (event) => {
  if (event.data.type === "ario-jwt-success") {
    localStorage.setItem("ario-jwt", event.data.token);
    localStorage.setItem("ario-jwt-expires-at", event.data.expiresAt);
    captchaWindow?.close();

    // Claim tokens
    const recipientAddress = await window.arweaveWallet.getActiveAddress(); // Example recipient
    const quantityToClaim = new ARIOToken(100).toMARIO().valueOf(); // 100 ARIO

    await ario.faucet
      .claimWithAuthToken({
        authToken: event.data.token,
        recipient: recipientAddress,
        quantity: quantityToClaim,
      })
      .then((res) => {
        alert("Successfully claimed 100 ARIO tokens! Transaction ID: " + res.id);
      })
      .catch((err) => {
        alert(`Failed to claim tokens: ${err}`);
      });
  }
});

// Example of checking and reusing a valid token
if (
  localStorage.getItem("ario-jwt-expires-at") &&
  Date.now() < parseInt(localStorage.getItem("ario-jwt-expires-at") ?? "0")
) {
  const validAuthToken = localStorage.getItem("ario-jwt") ?? "";
  const recipientAddress = await window.arweaveWallet.getActiveAddress();
  const quantityToClaim = new ARIOToken(100).toMARIO().valueOf();

  await ario.faucet.claimWithAuthToken({
    authToken: validAuthToken,
    recipient: recipientAddress,
    quantity: quantityToClaim,
  });
}
```
```

--------------------------------

### Initialize AR.IO SDK in Browser Bundle

Source: https://github.com/ar-io/ar-io-sdk/blob/main/README.md

This snippet demonstrates how to use the AR.IO SDK directly in a browser via a module bundle. Replace `<version>` with the specific release version. Ensure you have the correct versions of `@solana/kit` imported.

```html
<script type="module">
  // replace <version> with a release version
  import { ARIO } from 'https://github.com/ar-io/ar-io-sdk/releases/download/v<version>/web.bundle.min.js';
  import { createSolanaRpc } from 'https://esm.sh/@solana/kit@6';

  const ario = ARIO.init({
    rpc: createSolanaRpc('https://api.mainnet-beta.solana.com'),
  });
  const gateways = await ario.getGateways();
</script>
```

--------------------------------

### Display AR.IO CLI Help

Source: https://github.com/ar-io/ar-io-sdk/blob/main/CLI.md

View a list of all available commands for the AR.IO CLI.

```bash
ar.io --help
```

--------------------------------

### Initialize AR.IO SDK in Web Projects

Source: https://github.com/ar-io/ar-io-sdk/blob/main/README.md

Use this snippet to initialize the ARIO client with a Solana RPC endpoint for web applications. Ensure necessary polyfills for crypto, process, and buffer are available if your bundler does not provide them.

```javascript
import { ARIO } from '@ar.io/sdk';
import { createSolanaRpc } from '@solana/kit';

const ario = ARIO.init({
  rpc: createSolanaRpc('https://api.mainnet-beta.solana.com'),
});
const gateways = await ario.getGateways();
```

--------------------------------

### Initialize AR.IO SDK with Write Operations (Signer + WebSocket)

Source: https://github.com/ar-io/ar-io-sdk/blob/main/README.md

Initialize the AR.IO SDK for write operations, requiring a Solana RPC client, WebSocket subscriptions for transaction confirmation, and a signer. The signer must be created using appropriate credentials.

```typescript
import { ARIO } from '@ar.io/sdk';
import {
  createSolanaRpc,
  createSolanaRpcSubscriptions,
  createKeyPairSignerFromBytes,
} from '@solana/kit';

const rpc = createSolanaRpc('https://api.mainnet-beta.solana.com');
const rpcSubscriptions = createSolanaRpcSubscriptions(
  'wss://api.mainnet-beta.solana.com',
);
const signer = await createKeyPairSignerFromBytes(/* ... */);

const ario = ARIO.init({ rpc, rpcSubscriptions, signer });
```

--------------------------------

### Get ANT Name

Source: https://github.com/ar-io/ar-io-sdk/blob/main/README.md

Returns the name of the ANT. Note that this is distinct from the ArNS name.

```typescript
const name = await ant.getName();
```

--------------------------------

### Initialize AR-IO SDK and Crank Epoch Step

Source: https://github.com/ar-io/ar-io-sdk/blob/main/README.md

Initializes the AR-IO SDK and demonstrates how to advance the epoch lifecycle by one step. This can be run in a loop or on an interval.

```typescript
const ario = ARIO.init({ rpc, rpcSubscriptions, signer });

// one step
const result = await ario.crankEpochStep();
// → { action, epochIndex?, txId?, progress? }
//   action ∈ create | tally | prescribe | distribute | close
//          | close_observation | compound | update_demand_factor
//          | prune_returned_names | idle

// or drive it on an interval
setInterval(async () => {
  const r = await ario.crankEpochStep();
  if (r.action !== 'idle') console.log(r.action, r.epochIndex, r.txId);
}, 60_000);
```

--------------------------------

### Get ANT Logo Transaction ID

Source: https://github.com/ar-io/ar-io-sdk/blob/main/README.md

Retrieves the transaction ID of the logo set for the ANT.

```typescript
const logoTxId = await ant.getLogo();
```

--------------------------------

### Get Withdrawals

Source: https://github.com/ar-io/ar-io-sdk/blob/main/README.md

Returns pending stake withdrawals for an address. Withdrawals are claimable when Date.now() >= endTimestamp.

```typescript
const ario = ARIO.init({ rpc, rpcSubscriptions, signer });

const withdrawals = await ario.getWithdrawals({
  address: "9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin",
});

const claimable = withdrawals.items.filter(
  (w) => Date.now() >= w.endTimestamp,
);
```

--------------------------------

### AR.IO SDK Initialization

Source: https://github.com/ar-io/ar-io-sdk/blob/main/README.md

Initialize the AR.IO SDK by providing RPC client and program IDs. The SDK defaults to mainnet-beta but can be configured for devnet or local validators.

```APIDOC
## Initialization

### Description
Initialize the AR.IO SDK with your Solana RPC client and program IDs. This setup allows the SDK to interact with the AR.IO network.

### Method
`ARIO.init(config: { rpc: RpcClient, coreProgramId: Address, garProgramId: Address, arnsProgramId: Address, antProgramId: Address })`

### Parameters
*   **rpc** (RpcClient) - Required - An instance of the Solana RPC client.
*   **coreProgramId** (Address) - Required - The program ID for the AR.IO core functionality.
*   **garProgramId** (Address) - Required - The program ID for the AR.IO GAR (Get And Retrieve) service.
*   **arnsProgramId** (Address) - Required - The program ID for the AR.IO ARNS (AR.IO Name Service).
*   **antProgramId** (Address) - Required - The program ID for the AR.IO ANT (AR.IO Network Token) service.

### Request Example
```typescript
import { ARIO } from '@ar.io/sdk';
import { createSolanaRpc, address } from '@solana/kit';

const ario = ARIO.init({
  rpc: createSolanaRpc('https://api.devnet.solana.com'),
  coreProgramId: address('<ARIO_CORE_PROGRAM_ID>'),
  garProgramId: address('<ARIO_GAR_PROGRAM_ID>'),
  arnsProgramId: address('<ARIO_ARNS_PROGRAM_ID>'),
  antProgramId: address('<ARIO_ANT_PROGRAM_ID>'),
});
```
```

--------------------------------

### Get Allowed Delegates

Source: https://github.com/ar-io/ar-io-sdk/blob/main/README.md

Retrieves all allowed delegates for a specific address. The cursor is used for pagination.

```typescript
const ario = ARIO.init({ rpc });
const allowedDelegates = await ario.getAllowedDelegates({
  address: "QGWqtJdLLgm2ehFWiiPzMaoFLD50CnGuzZIPEdoDRGQ",
});
```

--------------------------------

### Get All Token Balances

Source: https://github.com/ar-io/ar-io-sdk/blob/main/README.md

Retrieves all token balances for the ANT. This is useful for an overview of an account's holdings.

```typescript
const balances = await ant.getBalances();
```

--------------------------------

### Initialize AR.IO SDK and Fetch Data

Source: https://github.com/ar-io/ar-io-sdk/blob/main/examples/web/index.html

Initializes the AR.IO SDK with a Solana RPC endpoint and fetches gateway information, user balance, ArNS records, observations, and distributions. This snippet is intended for use on page load.

```javascript
tailwind.config = {
  theme: {
    borderWidth: {
      1: "1px",
    },
    extend: {
      colors: {
        primary: "#FFBB38",
        background: "#141416",
        surface: "#222224",
        surfaceSecondary: "#2E2E30",
        textPrimary: "#F5F5F5",
        textSubtle: "#7A7A7C",
      },
    },
  },
};
// For local development, use the built bundle at ../../bundles/web.bundle.min.js
// For production, use GitHub Releases: https://github.com/ar-io/ar-io-sdk/releases/download/v<version>/web.bundle.min.js

import { ARIO, mARIOToken, } from "../../bundles/web.bundle.min.js";
import { createSolanaRpc } from "https://esm.sh/@solana/kit@6";

const rpc = createSolanaRpc("https://api.mainnet-beta.solana.com");
const ario = ARIO.init({ rpc });

// Sample wallet address for the balance demo below.
const sampleAddress = "11111111111111111111111111111111";

// fetch data on page load
async function init() {
  const gateways = await ario.getGateways();
  const balance = await ario
    .getBalance({ address: sampleAddress })
    .then((mARIO) => new mARIOToken(mARIO).toARIO());
  const record = await ario.getArNSRecord({ name: "ardrive" });
  const records = await ario.getArNSRecords();
  const observations = await ario.getObservations();
  const distributions = await ario.getDistributions();

  // update the UI
  document.getElementById("table-body").innerHTML = Object.entries(
    gateways,
  )
    .map(([gatewayOwner, gateway]) => {
      return ` 
        <tr> 
          <td class="border border-surface px-4 py-2 text-primary" style="width: fit-content"><a href="https://${gateway.settings.fqdn}" target="_blank">${gateway.settings.fqdn}</a></td> 
          <td class="border border-surface px-4 py-2 text-primary"><a href="https://arscan.io/address/${gatewayOwner}" target="_blank">${gatewayOwner}</a></td> 
          <td class="border border-surface px-4 py-2">${gateway.operatorStake} ARIO</td> 
        </tr> 
      `;
    })
    .join("");
  document.getElementById("balance-result").textContent = `Balance: ${balance} ARIO`;
  document.getElementById("record-result").textContent = JSON.stringify(
    record,
    null,
    2,
  );
  document.getElementById("records-table-body").innerHTML = Object.entries(records)
    .map(([domain, record]) => {
      return ` 
        <tr> 
          <td class="border border-surface px-4 py-2 text-primary"><a href="https://${domain}.arweave.dev" target="_blank">${domain}</a></td> 
          <td class="border border-surface px-4 py-2 text-primary"><a href="https://arscan.io/tx/${record.contractTxId}" target="_blank">${record.contractTxId}</a></td> 
          <td class="border border-surface px-4 py-2">${record.endTimestamp ? "Lease" : "Permanent"}</td> 
        </tr> 
      `;
    })
    .join("");
  document.getElementById("observations-table-body").innerHTML = Object.entries(observations)
    .map(([epoch, observationData]) => {
      return ` 
        <tr> 
          <td class="border border-surface px-4 py-2 text-primary"><a href="https://arscan.io/block/${epoch}" target="_blank">${epoch}</a></td> 
          <td class="border border-surface px-4 py-2 text-primary">${Object.keys(observationData.reports).length}</td> 
          <td class="border border-surface px-4 py-2">${Object.keys(observationData.failureSummaries).length}</td> 
        </tr> 
      `;
    })
    .join("");
  document.getElementById("distributions-table-body").innerHTML = ` 
        <tr> 
          <td class="border border-surface px-4 py-2 text-primary">${distributions.epochPeriod}</a></td> 
          <td class="border border-surface px-4 py-2 text-primary">${distributions.epochStartHeight}</td> 
          <td class="border border-surface px-4 py-2">${distributions.epochEndHeight}</td> 
          <td class="border border-surface px-4 py-2">${distributions.nextDistributionHeight}</td> 
        </tr> 
      `;
  // end init
}

window.addEventListener("load", init);

```

--------------------------------

### Get Specific Returned Name

Source: https://github.com/ar-io/ar-io-sdk/blob/main/README.md

Retrieves the data for a specific returned name. Requires the name as input.

```typescript
const ario = ARIO.init({ rpc });
const returnedName = await ario.getArNSReturnedName({ name: "permalink" });
```

--------------------------------

### Initialize TokenEscrow Client

Source: https://github.com/ar-io/ar-io-sdk/blob/main/README.md

Initializes the TokenEscrow client with necessary connection and program details. Ensure all parameters like rpc, signer, and programId are correctly configured.

```typescript
import { TokenEscrow, canonicalMessageV2 } from '@ar.io/sdk';

const escrow = new TokenEscrow({
  rpc,
  rpcSubscriptions,
  signer,
  programId,
  coreProgram,
});
```

--------------------------------

### Get Specific Token Balance

Source: https://github.com/ar-io/ar-io-sdk/blob/main/README.md

Retrieves the balance of a specific token address. Ensure the address is correctly formatted.

```typescript
const balance = await ant.getBalance({
  address: "ccp3blG__gKUvG3hsGC2u06aDmqv4CuhuDJGOIg0jw4",
});
```

--------------------------------

### Get Observations for an Epoch

Source: https://github.com/ar-io/ar-io-sdk/blob/main/README.md

Fetches the epoch-indexed observation list. Defaults to the current epoch if no epoch index is specified.

```typescript
const ario = ARIO.init({ rpc });
const observations = await ario.getObservations();
```

--------------------------------

### Get Current Epoch Data

Source: https://github.com/ar-io/ar-io-sdk/blob/main/README.md

Fetches the data for the current epoch. Initializes the ARIO SDK with the RPC endpoint.

```typescript
const ario = ARIO.init({ rpc });
const epoch = await ario.getCurrentEpoch();
```

--------------------------------

### AR.IO CLI Usage and Options

Source: https://github.com/ar-io/ar-io-sdk/blob/main/CLI.md

Displays the general usage of the AR.IO CLI, including available global options for wallet configuration, network selection, and debugging.

```sh
Usage: ar.io [options] [command]

AR.IO Network CLI

Options:
  -V, --version                           output the version number
  -w, --wallet-file <walletFilePath>      The file path to the wallet to use for the interaction
  --private-key <key>                     Stringified private key to use with the action
  --mainnet                               Run against AR.IO mainnet (Solana)
  --debug                                 Enable debug log output
  --rpc-url <rpcUrl>                      Solana RPC URL (defaults to mainnet-beta)
  --ant-program-id <antProgramId>         Override the ario-ant program id
  --core-program-id <coreProgramId>       Override the ario-core program id
  --gar-program-id <garProgramId>         Override the ario-gar program id
  --arns-program-id <arnsProgramId>       Override the ario-arns program id
  -h, --help                              display help for command

Commands:
  # ARIO Network

  # Getters
  info [options]                          Get network info
  token-supply [options]                  Get the total token supply
  balance [options]                       Get the balance of an address
  get-registration-fees [options]         Get registration fees
  get-demand-factor [options]             Get demand factor
  get-demand-factor-settings [options]    Get current settings for demand factor
  get-epoch-settings [options]            Get current settings for epochs
  get-gateway [options]                   Get the gateway of an address
  get-gateway-delegates [options]         Get the delegates of a gateway
  get-gateway-vaults [options]            Get the vaults of a gateway
  get-withdrawals [options]               Get all pending stake withdrawals (operator + delegate) owned by an address
  get-delegations [options]               Get all stake delegated to gateways from this address
  get-allowed-delegates [options]         Get the allow list of a gateway delegate
  get-arns-record [options]               Get an ArNS record by name
  get-arns-reserved-name [options]        Get a reserved ArNS name
  get-arns-returned-name [options]        Get an ArNS returned name by name
  get-epoch [options]                     Get epoch data
  get-current-epoch [options]             Get current epoch data
  get-prescribed-observers [options]      Get prescribed observers for an epoch
  get-prescribed-names [options]          Get prescribed names for an epoch
  get-observations [options]              Get observations for an epoch
  get-distributions [options]             Get distributions for an epoch
  get-eligible-rewards [options]          Get eligible distributions for an epoch
  get-token-cost [options]                Get token cost for an intended action
  get-cost-details [options]              Get expanded cost details for an intended action
  get-primary-name [options]              Get primary name
  get-primary-name-request [options]      Get primary name request
  get-redelegation-fee [options]          Get redelegation fee
  get-vault [options]                     Get the vault of provided address and vault ID

  # ArNS Resolution
  resolve-arns-name [options]             Resolve an ArNS name

  # Paginated handlers
  list-gateways [options]                 List the gateways of the network
  list-all-delegates [options]            List all paginated delegates from all gateways
  list-arns-records [options]             List all ArNS records
  list-arns-reserved-names [options]      Get all reserved ArNS names
  list-arns-returned-names [options]      Get all ArNS recently returned names
  list-vaults [options]                   Get all wallet vaults
  list-primary-name-requests [options]    Get primary name requests
  list-primary-names [options]            Get primary names
  list-balances [options]                 List all balances
  list-all-gateway-vaults [options]       List vaults from all gateways

```

--------------------------------

### Initialize ANT Client (Read-only and Writeable)

Source: https://github.com/ar-io/ar-io-sdk/blob/main/README.md

Factory method to create an ANT client. Provide signer and rpcSubscriptions for write capabilities.

```typescript
import { ANT } from '@ar.io/sdk';
import {
  createSolanaRpc,
  createSolanaRpcSubscriptions,
} from '@solana/kit';

const rpc = createSolanaRpc('https://api.mainnet-beta.solana.com');

// Read-only
const ant = await ANT.init({
  processId: '<MPL Core asset pubkey>',
  rpc,
});

// Read + write
const antWrite = await ANT.init({
  processId: '<MPL Core asset pubkey>',
  rpc,
  rpcSubscriptions: createSolanaRpcSubscriptions(
    'wss://api.mainnet-beta.solana.com',
  ),
  signer,
});
```

--------------------------------

### Get All Returned Names (Paginated)

Source: https://github.com/ar-io/ar-io-sdk/blob/main/README.md

Retrieves all active returned names, paginated and sorted. Use the cursor for pagination.

```typescript
const ario = ARIO.init({ rpc });
const returnedNames = await ario.getArNSReturnedNames({
  limit: 100,
  sortBy: "endTimestamp",
  sortOrder: "asc", // return the returned names ending soonest first
});
```

--------------------------------

### Spawn New ANT Asset

Source: https://github.com/ar-io/ar-io-sdk/blob/main/README.md

Static factory to mint a new MPL Core asset and initialize ANT PDAs in one transaction. Requires signer and rpcSubscriptions for write operations.

```typescript
import { ANT } from '@ar.io/sdk';

const { processId, signature } = await ANT.spawn({
  rpc,
  rpcSubscriptions,
  signer,
  state: {
    name: 'My ANT',
    ticker: 'MYANT',
    description: 'My ANT token',
    uri: 'ar://<metadata-tx-id>',
  },
});
```

--------------------------------

### Get ArNS Records for an Address

Source: https://github.com/ar-io/ar-io-sdk/blob/main/README.md

Retrieves all registered ArNS records for a given address, supporting pagination and sorting.

```typescript
const ario = ARIO.init({ rpc });
const records = await ario.getArNSRecordsForAddress({
  address: "t4Xr0_J4Iurt7caNST02cMotaz2FIbWQ4Kbj616RHl3",
  limit: 100,
  sortBy: "startTimestamp",
  sortOrder: "desc",
});
```

--------------------------------

### Get All Delegates

Source: https://github.com/ar-io/ar-io-sdk/blob/main/README.md

Retrieves all delegates across gateways, with pagination and sorting options. The cursor is used for subsequent paginated requests.

```typescript
const ario = ARIO.init({ rpc });
const delegates = await ario.getAllDelegates({
  limit: 2,
  sortBy: "startTimestamp",
  sortOrder: "desc",
});
```

--------------------------------

### Build and Run CLI Locally

Source: https://github.com/ar-io/ar-io-sdk/blob/main/CLI.md

Build the project's ESM output and then execute the CLI script with a specific command. Ensure you have run `yarn build:esm` before executing the CLI.

```bash
yarn build:esm
node lib/esm/cli/cli.js <command>
```

--------------------------------

### Initialize AR.IO SDK with Basic Read-Only RPC

Source: https://github.com/ar-io/ar-io-sdk/blob/main/README.md

Initialize the AR.IO SDK for read-only operations using a basic Solana RPC client. Ensure the RPC URL is correctly specified.

```typescript
import { ARIO } from '@ar.io/sdk';
import { createSolanaRpc } from '@solana/kit';

const rpc = createSolanaRpc('https://api.mainnet-beta.solana.com');
const ario = ARIO.init({ rpc });
```

--------------------------------

### Get All Gateway Vaults

Source: https://github.com/ar-io/ar-io-sdk/blob/main/README.md

Retrieves all vaults across all gateways, paginated and sorted. The cursor is the last vaultId from the previous request.

```typescript
const ario = ARIO.init({ rpc });
const vaults = await ario.getAllGatewayVaults({
  limit: 1,
  sortBy: "endTimestamp",
  sortOrder: "desc",
});
```

--------------------------------

### Get Wallet Balance

Source: https://github.com/ar-io/ar-io-sdk/blob/main/README.md

Retrieves the balance of a specified wallet address in mARIO. The result can be converted to ARIO for better readability.

```typescript
const ario = ARIO.init({ rpc });
// the balance will be returned in mARIO as a value
const balance = await ario
  .getBalance({
    address: "QGWqtJdLLgm2ehFWiiPzMaoFLD50CnGuzZIPEdoDRGQ",
  })
  .then((balance: number) => new mARIOToken(balance).toARIO()); // convert it to ARIO for readability
```

--------------------------------

### Initialize AR.IO SDK with Custom Network Configuration

Source: https://github.com/ar-io/ar-io-sdk/blob/main/README.md

Initialize the AR.IO SDK pointing to a specific Solana cluster and program IDs. This is useful for connecting to devnet or local validators.

```typescript
import { ARIO } from '@ar.io/sdk';
import { createSolanaRpc, address } from '@solana/kit';

const ario = ARIO.init({
  rpc: createSolanaRpc('https://api.devnet.solana.com'),
  coreProgramId: address('<ARIO_CORE_PROGRAM_ID>'),
  garProgramId: address('<ARIO_GAR_PROGRAM_ID>'),
  arnsProgramId: address('<ARIO_ARNS_PROGRAM_ID>'),
  antProgramId: address('<ARIO_ANT_PROGRAM_ID>'),
});
```

--------------------------------

### Initialize ARIO Client (Read-Only and Read-Write)

Source: https://github.com/ar-io/ar-io-sdk/blob/main/README.md

Factory function to create ARIO clients. Provide a signer for write methods; otherwise, the client is read-only. Requires rpcSubscriptions for write operations.

```typescript
import { ARIO } from '@ar.io/sdk';
import {
  createSolanaRpc,
  createSolanaRpcSubscriptions,
  createKeyPairSignerFromBytes,
} from '@solana/kit';

const rpc = createSolanaRpc('https://api.mainnet-beta.solana.com');

// read-only client
const ario = ARIO.init({ rpc });

// read-write client (needs rpcSubscriptions for sendAndConfirm)
const rpcSubscriptions = createSolanaRpcSubscriptions(
  'wss://api.mainnet-beta.solana.com',
);
const signer = await createKeyPairSignerFromBytes(/* 64-byte secret key */);
const arioWrite = ARIO.init({ rpc, rpcSubscriptions, signer });
```

--------------------------------

### Get All ANT Records

Source: https://github.com/ar-io/ar-io-sdk/blob/main/README.md

Returns all records associated with the configured ANT process. This includes the essential '@' record for resolving ArNS names.

```typescript
const records = await ant.getRecords();
```

--------------------------------

### ARIO.init

Source: https://github.com/ar-io/ar-io-sdk/blob/main/README.md

Factory function to create a read-only or writeable ARIO client. Providing a signer and rpcSubscriptions enables write methods.

```APIDOC
## ARIO.init({ rpc, rpcSubscriptions?, signer? })

### Description
Factory function that creates a read-only or writeable ARIO client. Providing `signer` plus `rpcSubscriptions` enables write methods (`joinNetwork`, `delegateStake`, `buyRecord`, etc.). Without a signer, the client is read-only.

### Parameters
* **rpc** - The RPC client for interacting with the network.
* **rpcSubscriptions** - Optional. The RPC subscriptions client, required for write operations.
* **signer** - Optional. The signer object, required for write operations.
```

--------------------------------

### Get ANT Controllers

Source: https://github.com/ar-io/ar-io-sdk/blob/main/README.md

Returns the wallet addresses of the controllers for the configured ANT process. Controllers have specific permissions to manage the ANT.

```typescript
const controllers = await ant.getControllers();
```

--------------------------------

### Get ANT Ticker

Source: https://github.com/ar-io/ar-io-sdk/blob/main/README.md

Returns the ticker symbol of the ANT. This is a short identifier for the ANT, often used in trading or display contexts.

```typescript
const ticker = await ant.getTicker();
```

--------------------------------

### Get Supported Handlers

Source: https://github.com/ar-io/ar-io-sdk/blob/main/README.md

Retrieves the handlers supported on the ANT. This is useful for understanding the full range of operations available for a given ANT.

```typescript
const handlers = await ant.getHandlers();
```

--------------------------------

### Get Prescribed Observers

Source: https://github.com/ar-io/ar-io-sdk/blob/main/README.md

Retrieves the prescribed observers for the ARIO process. Allows fetching data for a previous epoch by setting the `epochIndex`.

```typescript
const ario = ARIO.init({ rpc });
const observers = await ario.getPrescribedObservers({ epochIndex: 0 });
```

--------------------------------

### ANT.init

Source: https://github.com/ar-io/ar-io-sdk/blob/main/README.md

Factory function to create a read-only or writeable ANT client. Requires the process ID of the ANT and an RPC endpoint. Providing signer and rpcSubscriptions enables write operations.

```APIDOC
## ANT.init

### Description
Factory that creates a read-only or writeable ANT client. Providing `signer` and `rpcSubscriptions` enables write methods (`setRecord`, `transfer`, `addController`, etc.).

### Method Signature
`init({ processId, rpc, rpcSubscriptions?, signer? })`

### Parameters
- **processId** (string) - Required - The Metaplex Core asset's mint public key.
- **rpc** (object) - Required - An RPC client instance.
- **rpcSubscriptions** (object) - Optional - An RPC subscriptions client instance, required for write operations.
- **signer** (object) - Optional - A signer instance, required for write operations.
```

--------------------------------

### ANT.spawn

Source: https://github.com/ar-io/ar-io-sdk/blob/main/README.md

Static factory method to mint a new Metaplex Core asset and initialize the associated 'ario-ant' PDAs in a single transaction. Returns the process ID, mint public key, and transaction signature.

```APIDOC
## ANT.spawn

### Description
Static factory that mints a new MPL Core asset and initializes the `ario-ant` PDAs in a single transaction. Returns `{ processId, mint, signature }`.

### Method Signature
`ANT.spawn({ rpc, rpcSubscriptions, signer, state })`

### Parameters
- **rpc** (object) - Required - An RPC client instance.
- **rpcSubscriptions** (object) - Required - An RPC subscriptions client instance.
- **signer** (object) - Required - A signer instance.
- **state** (object) - Required - The initial state for the ANT.
  - **state.name** (string) - Required - Display name of the ANT.
  - **state.ticker** (string) - Optional - Ticker symbol.
  - **state.description** (string) - Optional - Short description.
  - **state.uri** (string) - Required - `ar://` URI of the Metaplex Core asset's JSON metadata.
  - **state.keywords** (string[]) - Optional - Keywords associated with the ANT.
  - **state.logo** (string) - Optional - Arweave TX ID of the logo.
  - **state.transactionId** (string) - Optional - Initial `@` record target.

### Returns
- **processId** (string) - The MPL Core asset mint pubkey.
- **mint** (Address) - The mint address.
- **signature** (string) - The Solana transaction signature.
```

--------------------------------

### Get Epoch Data by Index

Source: https://github.com/ar-io/ar-io-sdk/blob/main/README.md

Retrieves epoch data for a specific epoch index. If no index is provided, it defaults to the current epoch.

```typescript
const ario = ARIO.init({ rpc });
const epoch = await ario.getEpoch({ epochIndex: 0 });
```

--------------------------------

### CLI Usage for Spawning ANT

Source: https://github.com/ar-io/ar-io-sdk/blob/main/README.md

Command-line interface command to spawn a new ANT asset. Requires wallet file and ANT metadata details.

```bash
ar.io spawn-ant \
  --wallet-file wallet.json \
  --name "My ANT" \
  --ticker "MYANT" \
  --metadata-uri "ar://<metadata-tx-id>"
```

--------------------------------

### Get Redelegation Fee

Source: https://github.com/ar-io/ar-io-sdk/blob/main/README.md

Retrieves the current redelegation fee rate as a percentage for a specific address. The fee can range from 0% to 60%.

```typescript
const ario = ARIO.init({ rpc });

const fee = await ario.getRedelegationFee({
  address: "t4Xr0_J4Iurt7caNST02cMotaz2FIbWQ4Kbj616RHl3",
});
```

--------------------------------

### Import Generated Instruction Builders

Source: https://github.com/ar-io/ar-io-sdk/blob/main/README.md

Import Codama-generated typed clients for building custom transactions. These builders are available from the `@ar.io/solana-contracts` package.

```typescript
import {
  getBuyNameInstructionAsync,
  ARIO_ARNS_PROGRAM_ADDRESS,
} from '@ar.io/solana-contracts/arns';
```

--------------------------------

### Get Delegations

Source: https://github.com/ar-io/ar-io-sdk/blob/main/README.md

Retrieves paginated and sorted stakes for a given address. Uses a cursor for pagination, which is the last delegationId from the previous request.

```typescript
const ario = ARIO.init({ rpc });
const vaults = await ario.getDelegations({
  address: "t4Xr0_J4Iurt7caNST02cMotaz2FIbWQ4Kbj616RHl3",
  cursor: "QGWqtJdLLgm2ehFWiiPzMaoFLD50CnGuzZIPEdoDRGQ_123456789",
  limit: 2,
  sortBy: "startTimestamp",
  sortOrder: "asc",
});
```

--------------------------------

### Update Own Record (Correctly)

Source: https://github.com/ar-io/ar-io-sdk/blob/main/README.md

Example of a record owner updating their own record by correctly including their own address in the 'owner' field. This action maintains their ownership.

```typescript
// Alice (record owner) updating her own record
const aliceAnt = await ANT.init({
  processId: 'ANT_MINT_PUBKEY',
  rpc,
  rpcSubscriptions,
  signer: aliceSigner, // Alice's @solana/kit signer
});

// ✅ CORRECT: Alice includes her own address as owner
const { id: txId } = await aliceAnt.setUndernameRecord({
  undername: "alice",
  transactionId: "new-content-tx-id-456...",
  ttlSeconds: 1800,
  owner: "alice-wallet-address-123...", // MUST be Alice's own address
  displayName: "Alice Updated Portfolio",
  description: "Updated personal portfolio and blog",
});
```