@satoshai/abi-cli

CLI tool to fetch ABIs from deployed Stacks blockchain contracts and output TypeScript-ready definitions (as const).

Install

# Global install
npm install -g @satoshai/abi-cli

# Or run directly with npx
npx @satoshai/abi-cli fetch <contract>

Usage

Basic — fetch and write to file

By default, the CLI writes a TypeScript file named after the contract to the current directory:

abi-cli fetch SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.amm-pool-v2-01
# → writes amm-pool-v2-01.ts

The generated file looks like:

import type { ClarityAbi } from '@stacks/transactions';

// ABI for SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.amm-pool-v2-01
// Generated by @satoshai/abi-cli

export const abi = {
  "functions": [...],
  "variables": [...],
  ...
} as const satisfies ClarityAbi;

export type Abi = typeof abi;

Output to stdout

Use --stdout to print the output instead of writing a file:

abi-cli fetch SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.amm-pool-v2-01 --stdout

Custom output path

abi-cli fetch SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.amm-pool-v2-01 -o ./abis/amm-pool.ts

JSON format

# Write to file (amm-pool-v2-01.json)
abi-cli fetch SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.amm-pool-v2-01 --format json

# Print to stdout
abi-cli fetch SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.amm-pool-v2-01 --format json --stdout

Networks

Defaults to mainnet. Use -n / --network to switch:

# Testnet
abi-cli fetch ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.my-contract -n testnet

# Devnet (localhost:3999)
abi-cli fetch ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.my-contract -n devnet

# Custom Stacks API URL
abi-cli fetch SP...contract -n https://my-node.example.com

Multiple contracts

Comma-separate contract IDs to fetch several at once:

abi-cli fetch SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.amm-pool-v2-01,SP2C2YFP12AJZB1KD5HQ4XFRYGEK02H70HVK8GQH.arkadiko-swap-v2-1
# → writes amm-pool-v2-01.ts and arkadiko-swap-v2-1.ts

Sync — config-driven multi-contract sync

For projects with multiple contracts, create a config file to keep ABIs in sync declaratively.

Create abi.config.json in your project root:

{
  "outDir": "./src/abis",
  "format": "ts",
  "network": "mainnet",
  "contracts": [
    { "id": "SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.amm-pool-v2-01", "name": "amm-pool" },
    { "id": "SP2C2YFP12AJZB1KD5HQ4XFRYGEK02H70HVK8GQH.arkadiko-swap-v2-1", "name": "arkadiko-swap" },
    { "id": "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.my-contract", "network": "testnet" }
  ]
}

The name field controls the output filename. This decouples your imports from the on-chain contract ID — when you upgrade to a new contract version, change the id but keep the name. Your imports stay the same.

Or use abi.config.ts for type-safe config with autocomplete:

import type { AbiConfig } from '@satoshai/abi-cli';

export default {
  outDir: './src/abis',
  format: 'ts',
  network: 'mainnet',
  contracts: [
    { id: 'SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.amm-pool-v2-01', name: 'amm-pool' },
    { id: 'SP2C2YFP12AJZB1KD5HQ4XFRYGEK02H70HVK8GQH.arkadiko-swap-v2-1', name: 'arkadiko-swap' },
  ],
} satisfies AbiConfig;

Then run:

abi-cli sync
# → reads abi.config.json (or .ts), writes all ABIs to outDir

This generates:

src/abis/
├── amm-pool.ts
├── arkadiko-swap.ts
└── index.ts          # barrel file with re-exports

The barrel file re-exports all ABIs with camelCase names:

export { abi as ammPoolAbi } from './amm-pool.js';
export { abi as arkadikoSwapAbi } from './arkadiko-swap.js';

Use --config / -c to point to a custom config path:

abi-cli sync --config ./configs/my-abis.json

Config schema

| Field | Type | Required | Default | Description | |-------|------|----------|---------|-------------| | outDir | string | yes | — | Output directory for generated files | | format | "ts" \| "json" | no | "ts" | Output format | | network | string | no | "mainnet" | Default network for all contracts | | contracts | ContractEntry[] | yes | — | List of contracts to sync | | contracts[].id | string | yes | — | Contract ID in address.name format | | contracts[].name | string | no | contract name from ID | Alias for output filename and barrel export | | contracts[].network | string | no | top-level network | Per-contract network override |

Check — CI staleness detection

Use --check to verify local files are in sync with on-chain ABIs without writing anything. Exits with code 1 if any files are stale or missing.

# Single contract
abi-cli fetch SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.amm-pool-v2-01 --check

# All contracts from config
abi-cli sync --check

Add it to your CI pipeline to catch stale types:

- name: Check ABIs are up-to-date
  run: npx @satoshai/abi-cli sync --check

Flags Reference

abi-cli fetch

| Flag | Alias | Default | Description | |------|-------|---------|-------------| | --network | -n | mainnet | Network: mainnet, testnet, devnet, or a custom URL | | --output | -o | <contract-name>.<format> | Output file path (single contract only) | | --format | -f | ts | Output format: ts or json | | --stdout | | false | Print to stdout instead of writing a file | | --check | | false | Check if local files match on-chain ABI (exit 1 if stale) | | --help | | | Show help |

abi-cli sync

| Flag | Alias | Default | Description | |------|-------|---------|-------------| | --config | -c | auto-discover | Path to config file | | --check | | false | Check if local files match on-chain ABIs (exit 1 if stale) | | --help | | | Show help |

Programmatic API

import { fetchContractAbi, generateTypescript, generateJson, parseContractId } from '@satoshai/abi-cli';

// Fetch an ABI
const abi = await fetchContractAbi('mainnet', 'SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM', 'amm-pool-v2-01');

// Generate TypeScript (as const)
const tsCode = generateTypescript('SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.amm-pool-v2-01', abi);

// Generate JSON
const json = generateJson(abi);

// Parse a contract ID string
const { address, name } = parseContractId('SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.amm-pool-v2-01');

Config loading

import { loadConfig, validateConfig } from '@satoshai/abi-cli';
import type { AbiConfig, ContractEntry } from '@satoshai/abi-cli';

// Load and validate from file (auto-discovers abi.config.json/.ts)
const config = await loadConfig();

// Or from a specific path
const config2 = await loadConfig('./my-config.json');

// Validate a raw object
const validated = validateConfig({ outDir: './abis', contracts: [{ id: 'SP1.token' }] });

Types are re-exported from @stacks/transactions:

import type { ClarityAbi, ClarityAbiFunction, ClarityAbiType } from '@satoshai/abi-cli';

License

MIT