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

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

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

The question should be specific, self-contained, and written in natural language.
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.