Payman SDK Integration

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

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

# Step 1: Install dependencies
python3 -m pip install payman-sdk-python

# Step 2: Initialize the Client

from payman_sdk import PaymanClient

payman = PaymanClient.with_credentials({
"client_id": "your-client-id",
"client_secret": "your-client-secret"
})

# Step 3: Make a request

response = payman.ask("Send $100 to Alice")
print(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:

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!,
});

Using OAuth Authorization Code (for OAuth flow):

const payman = PaymanClient.withAuthCode(
	{
		clientId: "your-client-id",
	},
	"your-auth-code"
);

Using an Existing Access Token (when you already have a token):

const payman = PaymanClient.withToken("your-client-id", {
	accessToken: "your-access-token",
	expiresIn: 3600,
});

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!,
});

Using OAuth Authorization Code (for OAuth flow):

const payman = PaymanClient.withAuthCode(
	{
		clientId: "your-client-id",
	},
	"your-auth-code"
);

Using an Existing Access Token (when you already have a token):

const payman = PaymanClient.withToken("your-client-id", {
	accessToken: "your-access-token",
	expiresIn: 3600,
});

Using Client Credentials (recommended)

from payman_sdk import PaymanClient

payman = PaymanClient.with_credentials({
    "client_id": "your-client-id",
    "client_secret": "your-client-secret"
})

Using OAuth Authorization Code (for OAuth flow):

payman = PaymanClient.with_auth_code(
    {
        "client_id": "your-client-id",
        "environment": "TEST"
    },
    "your-auth-code"
)

Using an Existing Access Token (when you already have a token):

payman = PaymanClient.with_token(
    "your-client-id",
    {
        "access_token": "your-access-token",
        "expires_in": 3600
    }
)

Making a Request

1. Basic usage (Recommended)

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" },
});

1. Basic usage (Recommended)

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" },
});

1. Basic usage (Recommended)

response = payman.ask("List all payees")
print(response)

2. Get Raw JSON-RPC Response

raw_response = payman.ask("List all payees", raw=True)
print(raw_response)

3. Streaming Responses

Use this to get updates in real-time:

payman.ask("List all wallets", {
    "on_message": lambda res: print("Formatted:", res)
})

4. Starting New Sessions with Metadata

response = payman.ask("Hello!", {
    "new_session": 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",
	},
});

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

payman.ask("Pay John $100", {
    "metadata": {
        "source": "mobile-app",
        "user_id": "abc123"
    },
    "message_metadata": {
        "priority": "high"
    },
    "part_metadata": {
        "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);
	}
}

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);
	}
}

import requests

try:
    response = payman.ask("Send $500 to Alex")
except requests.exceptions.RequestException as e:
    if hasattr(e, "response") and e.response is not None:
        print("API Error:", e.response.json())
        print("Status Code:", e.response.status_code)
    else:
        print("Setup error:", str(e))

Need help? Reach out to [email protected]

Overview

For Users

For Developers

Resources

Quickstart

What Payman SDK Does

Installation

Environment Setup

Initialize the SDK

Making a Request

1. Basic usage (Recommended)

2. Get Raw JSON-RPC Response

3. Streaming Responses

4. Starting New Sessions with Metadata

1. Basic usage (Recommended)

2. Get Raw JSON-RPC Response

3. Streaming Responses

4. Starting New Sessions with Metadata

1. Basic usage (Recommended)

2. Get Raw JSON-RPC Response

3. Streaming Responses

4. Starting New Sessions with Metadata

Adding Metadata

Session & Token Management

Error Handling

Overview

For Users

For Developers

Resources

​Quickstart

​What Payman SDK Does

​Installation

​Environment Setup

​Initialize the SDK

​Making a Request

​1. Basic usage (Recommended)

​2. Get Raw JSON-RPC Response

​3. Streaming Responses

​4. Starting New Sessions with Metadata

​1. Basic usage (Recommended)

​2. Get Raw JSON-RPC Response

​3. Streaming Responses

​4. Starting New Sessions with Metadata

​1. Basic usage (Recommended)

​2. Get Raw JSON-RPC Response

​3. Streaming Responses

​4. Starting New Sessions with Metadata

​Adding Metadata

​Session & Token Management

​Error Handling

Quickstart

What Payman SDK Does

Installation

Environment Setup

Initialize the SDK

Making a Request

1. Basic usage (Recommended)

2. Get Raw JSON-RPC Response

3. Streaming Responses

4. Starting New Sessions with Metadata

1. Basic usage (Recommended)

2. Get Raw JSON-RPC Response

3. Streaming Responses

4. Starting New Sessions with Metadata

1. Basic usage (Recommended)

2. Get Raw JSON-RPC Response

3. Streaming Responses

4. Starting New Sessions with Metadata

Adding Metadata

Session & Token Management

Error Handling