> For the complete documentation index, see [llms.txt](https://printr.gitbook.io/printr-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://printr.gitbook.io/printr-docs/for-developers/printr-sdk.md).

# Printr SDK \[NEW]

TypeScript SDK for [Printr](https://printr.money) — create and manage tokens across EVM chains and Solana.

* **NPM:** [@printr/sdk](https://www.npmjs.com/package/@printr/sdk)
* **GitHub:** [github.com/PrintrFi/printr-mcp](https://github.com/PrintrFi/printr-mcp)
* **Developer reference:** [full SDK reference](https://printrfi.github.io/printr-mcp/docs/sdk) — exports, types, and guides

## Features

* **Multi-chain support** — Deploy tokens on Base, Ethereum, Solana, and more
* **Secure wallet management** — Encrypted keystore with AES-256-GCM
* **Balance & transfers** — Query balances and transfer tokens across chains
* **Image generation** — AI-powered token avatar creation
* **Framework-agnostic** — Works with Node.js, Bun, and browsers
* **Type-safe** — Full TypeScript support with Zod schemas

***

## Installation

```bash
npm install @printr/sdk
# or
bun add @printr/sdk
# or
yarn add @printr/sdk
```

***

## Quick Start

### Create a Token

```typescript
import { createPrintrClient, buildToken } from '@printr/sdk';

const client = createPrintrClient({
  apiKey: process.env.PRINTR_API_KEY,
  baseUrl: process.env.PRINTR_API_BASE_URL ?? 'https://api-preview.printr.money',
});

const result = await buildToken({
  creator_accounts: ['eip155:8453:0xYourAddress'],
  name: 'My Token',
  symbol: 'TKN',
  description: 'A cool token',
  chains: ['eip155:8453'], // Base
  initial_buy: { spend_usd: 10 },
}, client);

if (result.isOk()) {
  console.log('Token created:', result.value.token_id);
}
```

### Sign and Submit Transactions

```typescript
import { signAndSubmitEvm } from '@printr/sdk/evm';
import { ResultAsync } from 'neverthrow';

buildToken(input, client)
  .andThen(({ token_id, payload }) =>
    ResultAsync.fromPromise(
      signAndSubmitEvm(payload, process.env.EVM_WALLET_PRIVATE_KEY!),
      (e) => ({ message: e instanceof Error ? e.message : String(e) }),
    ).map((tx) => ({ token_id, tx }))
  )
  .match(
    ({ token_id, tx }) => console.log('Token:', token_id, 'TX:', tx.tx_hash),
    (err) => console.error('Failed:', err.message),
  );
```

### Check Balances

```typescript
import { checkEvmBalance } from '@printr/sdk/balance';

const balance = await checkEvmBalance(
  '0xYourWalletAddress',
  8453, // Base chain ID
  21000, // gas limit estimate
);

balance.match(
  ({ balanceFormatted, symbol, sufficient }) =>
    console.log(`Balance: ${balanceFormatted} ${symbol} (sufficient: ${sufficient})`),
  (err) => console.error('Balance fetch failed:', err),
);
```

### Transfer Tokens

```typescript
import { executeTransfer } from '@printr/sdk/transfer';
import { getChainMeta } from '@printr/sdk/chains';

const meta = getChainMeta('eip155:8453')!;
const result = await executeTransfer(
  'eip155',
  '8453',
  '0xRecipientAddress',
  '1.5',
  process.env.EVM_WALLET_PRIVATE_KEY!,
  meta,
);

if (result.isOk()) {
  console.log('tx_hash' in result.value ? result.value.tx_hash : result.value.signature);
}
```

***

## Modules

The SDK is organized into focused modules:

```typescript
// Main exports
import { createPrintrClient, buildToken } from '@printr/sdk';

// Client utilities
import { createPrintrClient } from '@printr/sdk/client';

// Chain information
import { CHAIN_META, getChainMeta } from '@printr/sdk/chains';

// EVM operations
import { signAndSubmitEvm, normalisePrivateKey } from '@printr/sdk/evm';

// Solana operations
import { signAndSubmitSvm, getSvmRpcUrl } from '@printr/sdk/svm';

// Balance queries
import { checkEvmBalance, checkSvmBalance, getEvmNativeBalance } from '@printr/sdk/balance';

// Token transfers
import { executeTransfer, transferEvm, transferSvm } from '@printr/sdk/transfer';

// Wallet keystore
import { addWallet, decryptKey, encryptKey, listWallets } from '@printr/sdk/keystore';

// Image generation
import { generateImageFromPrompt, generateTokenImage } from '@printr/sdk/image';

// CAIP utilities
import { parseCaip2, parseCaip10, chainTypeFromCaip2 } from '@printr/sdk/caip';

// Staking API
import {
  listStakePositionsWithRewards,
  claimStakingRewards,
  parseStakingCaip10,
  formatStakingCaip10,
  StakingLockPeriod,
} from '@printr/sdk';
```

***

## Configuration

### Environment Variables

| Variable                     | Description                                                     |
| ---------------------------- | --------------------------------------------------------------- |
| `PRINTR_API_KEY`             | Optional API key. Defaults to public integration key            |
| `PRINTR_API_BASE_URL`        | API base URL (default: `https://api-preview.printr.money`)      |
| `OPENROUTER_API_KEY`         | For AI image generation                                         |
| `OPENROUTER_IMAGE_MODEL`     | Image model override (default: `google/gemini-2.5-flash-image`) |
| `EVM_WALLET_PRIVATE_KEY`     | Default EVM private key for signing                             |
| `SVM_WALLET_PRIVATE_KEY`     | Default Solana keypair secret for signing                       |
| `PRINTR_DEPLOYMENT_PASSWORD` | Master password for encrypted keystore (min 16 chars)           |

***

## Keystore Security

The SDK uses AES-256-GCM encryption with scrypt key derivation:

```typescript
import { encryptKey, addWallet, listWallets, type WalletEntry } from '@printr/sdk/keystore';
import { randomUUID } from 'node:crypto';

const encrypted = encryptKey('0x...', password);
const entry: WalletEntry = {
  id: randomUUID(),
  label: 'my-evm-wallet',
  chain: 'eip155:8453',
  address: '0xYourAddress',
  ...encrypted,
  createdAt: Date.now(),
};

addWallet(entry);

const wallets = listWallets();
console.log(wallets.map((w) => `${w.label}: ${w.address}`));
```

***

## Supported Chains

### EVM (CAIP-2 format)

| Chain           | CAIP-2 ID      |
| --------------- | -------------- |
| Ethereum        | `eip155:1`     |
| Base            | `eip155:8453`  |
| Arbitrum        | `eip155:42161` |
| Avalanche       | `eip155:43114` |
| BNB Smart Chain | `eip155:56`    |
| Monad           | `eip155:143`   |
| Mantle          | `eip155:5000`  |
| Unichain        | `eip155:130`   |
| HyperEVM        | `eip155:999`   |
| MegaETH         | `eip155:4326`  |
| Plasma          | `eip155:9745`  |

### Solana

| Network | CAIP-2 ID                                 |
| ------- | ----------------------------------------- |
| Mainnet | `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp` |

***

## Error Handling

Most operations return `ResultAsync<T, E>` from [neverthrow](https://github.com/supermacro/neverthrow):

```typescript
// Expression-style with .match()
buildToken(input, client).match(
  (value) => console.log('Token ID:', value.token_id),
  (error) => console.error('Failed:', error.message),
);

// Imperative with await
const result = await buildToken(input, client);
if (result.isErr()) {
  console.error('Error:', result.error.message);
  return;
}
console.log('Token ID:', result.value.token_id);
```

***

## API Reference

### Client

```typescript
createPrintrClient(options?: {
  apiKey?: string;
  baseUrl?: string;
}): PrintrClient
```

### Token Operations

```typescript
buildToken(input: BuildTokenInput, client: PrintrClient): ResultAsync<BuildTokenOutput, PrintrApiError>
getToken(tokenId: string, client: PrintrClient): ResultAsync<TokenDetails, PrintrApiError>
quoteToken(input: QuoteInput, client: PrintrClient): ResultAsync<QuoteOutput, PrintrApiError>
```

### Transaction Signing

```typescript
signAndSubmitEvm(payload: EvmPayload, privateKey: string, rpcUrl?: string): Promise<EvmSubmitResult>
signAndSubmitSvm(payload: SvmPayload, privateKey: string, rpcUrl?: string): Promise<SvmSubmitResult>
executeTransfer(namespace, chainRef, toAddress, amount, privateKey, meta): ResultAsync<TransferResult, TransferError>
```

***

## TypeScript

All types are exported:

```typescript
import type {
  BuildTokenInput,
  BuildTokenOutput,
  QuoteInput,
  QuoteOutput,
  TokenDetails,
  Chain,
  Keystore,
} from '@printr/sdk';
```

***

## Requirements

* Node.js 18+ or Bun 1.0+
* TypeScript 5.9+ (peer dependency)

***

## Resources

* [NPM Package](https://www.npmjs.com/package/@printr/sdk)
* [GitHub](https://github.com/PrintrFi/printr-mcp)
* [Printr API Docs](https://api-preview.printr.money/login#description/introduction)
* [Printr MCP](https://github.com/PrintrFi/gitbook/blob/master/for-developers/printr-mcp.md)