> 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`    |

### 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)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://printr.gitbook.io/printr-docs/for-developers/printr-sdk.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.