Getting Started

Quick Start

Go from zero to a completed testnet transfer in under ten minutes.

Updated Feb 23, 2026

This gets you from zero to a completed transfer in under ten minutes. We will do a simple USDC transfer on testnet so nothing real moves while you are getting familiar.

What you need

A Papillae account. An API key. Node.js 18 or above. That is it.

Step 1 - Install the SDK

bash1 lines

1npm install @papillae/sdk

Step 2 - Set up your client

typescript6 lines

1import { Papillae } from "@papillae/sdk";
2
3const client = new Papillae({
4  apiKey: process.env.PAPILLAE_API_KEY,
5  network: "testnet",
6});

Step 3 - Simulate a payment first

Always simulate before executing. This confirms the route is valid and shows you the fee and estimated time before anything moves.

typescript25 lines

1const simulation = await client.simulate({
2  from: {
3    address: "0xYourWalletAddress",
4    chain: "ethereum",
5    token: "USDC",
6    amount: 100,
7  },
8  to: {
9    address: "0xRecipientAddress",
10    chain: "polygon",
11    token: "USDC",
12  },
13  preferences: {
14    priority: "cost",
15  },
16});
17
18console.log(simulation);
19// {
20//   willSucceed: true,
21//   expectedOutput: 99.70,
22//   estimatedFee: 0.30,
23//   estimatedTime: "45 seconds",
24//   route: { hops: 1, protocol: "circle_cctp" }
25// }

Step 4 - Execute the payment

If simulation looks good, execute with one additional line.

typescript20 lines

1const payment = await client.execute({
2  from: {
3    address: "0xYourWalletAddress",
4    chain: "ethereum",
5    token: "USDC",
6    amount: 100,
7  },
8  to: {
9    address: "0xRecipientAddress",
10    chain: "polygon",
11    token: "USDC",
12  },
13  preferences: {
14    priority: "cost",
15  },
16  externalRef: "my-first-payment-001",
17});
18
19console.log(payment.paymentId);
20// pay_a1b2c3d4e5

Step 5 - Check status

typescript7 lines

1const status = await client.getStatus(payment.paymentId);
2
3console.log(status.status);
4// "settled"
5
6console.log(status.settledAt);
7// 2026-02-22T10:42:31Z

Or use natural language

If you want to try the intent parser instead of writing structured calls:

typescript1 lines

1const payment = await client.send("send 100 USDC to 0xRecipientAddress on polygon");

Same result. The intent parser extracted the structured data and executed it. This is the same path an AI agent uses.

What just happened

Your 100 USDC left your wallet on Ethereum. Papillae's smart contract routed it through Circle CCTP to Polygon. The recipient received 99.70 USDC. The 0.30 difference was the protocol fee plus bridge cost. The whole thing settled in under a minute.

That is Papillae. Everything else in this documentation is a deeper version of what you just did.

How It Works - 60 Second Version

Who Is This For