​
Quickstart

The Payman SDK makes it ridiculously easy to automate financial workflows with AI agents.

Get started in 3 steps:

# Step 1: Install the SDK
npm install @paymanai/payman-ts

# Step 2: Initialize the Client
import { PaymanClient } from "@paymanai/payman-ts";

const payman = PaymanClient.withCredentials({
  clientId: "your-client-id",
  clientSecret: "your-client-secret"
});

# Step 3: Make a request
const response = await payman.ask("Send $100 to Alice");
console.log(response);

That’s it — no API orchestration, no complex setup. The .ask() method handles everything.

​
What Payman SDK Does

The Payman SDK lets you:

  • Authenticate using client credentials, or authorization code.
  • Automate payments, send money, manage payees, and more
  • Use .ask() to issue natural language instructions
  • Attach metadata, stream real-time updates, and manage sessions

​
Installation

npm install @paymanai/payman-ts

​
Environment Setup

Before using the SDK, create a .env file and add:

PAYMAN_CLIENT_ID=your-client-id
PAYMAN_CLIENT_SECRET=your-client-secret

These credentials are required to authenticate API requests.

​
Initialize the SDK

The SDK supports 3 authentication methods:

  1. Using Client Credentials (recommended)
import { PaymanClient } from "@paymanai/payman-ts";

const payman = PaymanClient.withCredentials({
	clientId: process.env.PAYMAN_CLIENT_ID!,
	clientSecret: process.env.PAYMAN_CLIENT_SECRET!
});
  1. Using OAuth Authorization Code (for OAuth flow):
const payman = PaymanClient.withAuthCode(
	{
		clientId: "your-client-id",
	},
	"your-auth-code"
);
  1. Using an Existing Access Token (when you already have a token):
const payman = PaymanClient.withToken(
	"your-client-id",
	{
		accessToken: "your-access-token",
		expiresIn: 3600,
	}
);

​
Making a Request

const response = await payman.ask("List all payees");
console.log(response);

​
2. Get Raw JSON-RPC Response

const raw = await payman.ask("List all payees", undefined, true);
console.log(raw);

​
3. Streaming Responses

Use this to get updates in real-time:

await payman.ask("List all wallets", {
	onMessage: (res) => {
		console.log("Formatted:", res);
	},
});

Or get raw responses:

await payman.ask(
	"List all wallets",
	{
		onMessage: (res) => {
			console.log("Raw:", res);
		},
	},
	true
);

​
4. Starting New Sessions with Metadata

const response = await payman.ask("Hello!", {
	newSession: true,
	metadata: { source: "web-app" },
});

​
Adding Metadata

Attach contextual data to requests.

await payman.ask("Pay John $100", {
	metadata: {
		source: "mobile-app",
		userId: "abc123",
	},
	messageMetadata: {
		priority: "high",
	},
	partMetadata: {
		currency: "USD",
	},
});

​
Session & Token Management

  • Sessions persist across requests.
  • Use newSession: true to force a reset.
  • The SDK auto-refreshes tokens before expiry.
  • You can manually check or get access tokens:
const token = payman.getAccessToken();
const isExpired = payman.isAccessTokenExpired();

​
Error Handling

The SDK uses Axios internally. Catch errors like this:

try {
	await payman.ask("Send $500 to Alex");
} catch (err) {
	if (err.response) {
		console.error("API Error:", err.response.data);
	} else if (err.request) {
		console.error("No response:", err.request);
	} else {
		console.error("Setup error:", err.message);
	}
}

Need help? Reach out to [email protected]