> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pesapay.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Client reference

> Every method of the transfers client, with its types.

```ts theme={null}
const pesa = createTransfersClient({ baseUrl, getToken });
```

Every method returns a promise and throws `TransfersApiError` on a non-2xx reply.

```ts theme={null}
class TransfersApiError extends Error {
  status: number;   // HTTP status
  body: unknown;    // parsed JSON body, or the raw text
}
```

## getRoutes

```ts theme={null}
pesa.getRoutes(): Promise<RouteInfo[]>
```

Lists every route. Needs no token.

```ts theme={null}
interface RouteInfo {
  route: Route;                  // "cctp-deposit" | "usdt0-deposit" | "cctp-withdraw" | "usdt0-withdraw" | "stellar-send"
  network: "testnet" | "mainnet";
  source_chain: string;          // CAIP-2
  source_asset: string;          // CAIP-19 or stellar:CODE:ISSUER
  dest_chain: string;
  dest_asset: string;
  min: string;                   // base units
  max: string;
  funding_modes: ("deposit_address" | "direct")[];
  available: boolean;            // false while a relayer is low on fees
  typical_seconds: number;
}
```

## quote

```ts theme={null}
pesa.quote(req: QuoteRequest): Promise<QuoteResponse>
```

```ts theme={null}
interface QuoteRequest {
  route: Route;
  amount_in: string;             // source base units, as a decimal string
  source_chain: string;          // CAIP-2
  source_address: string;        // the user's EVM address, or their Stellar G address
  dest_address: string;          // deposits: must equal the owner
  dest_chain?: string;           // withdrawals: the destination CAIP-2
  funding_mode?: "deposit_address" | "direct";
}

interface QuoteResponse {        // SEP-38 fields
  id: string;
  expires_at: string;
  sell_asset: string;
  buy_asset: string;
  sell_amount: string;
  buy_amount: string;
  price: string;
  fee: { total: string; asset: string; details: { name: string; amount: string }[] };
}
```

A quote is a server-side record. Creating a transfer uses only its `id`, so the terms cannot be changed by the client.

## createTransfer

```ts theme={null}
pesa.createTransfer(quoteId: string, idempotencyKey: string): Promise<TransferView>
```

Creates a transfer from a quote. Calling it again with the same key returns the same transfer. A used or expired quote returns `409`.

## getActions

```ts theme={null}
pesa.getActions(id: string): Promise<Action | null>
```

Returns the one action the user can take now, or `null` when it is Pesa's or a chain's turn.

```ts theme={null}
type Action =
  | { kind: "send_to_address"; chain: string; asset: string; address: `0x${string}`; amount: string }
  | { kind: "evm_calls"; chainId: number; calls: { to: `0x${string}`; data: `0x${string}`; value: string }[] }
  | { kind: "stellar_tx"; xdr: string; network_passphrase: string }
  | { kind: "stellar_trustline"; asset: string };
```

| Kind | What your app does |
| - | - |
| `send_to_address` | Show the address and a QR code. Funding is detected automatically. |
| `evm_calls` | Verify the calls, then send them: one batched call on a smart wallet, or one transaction each on an injected wallet. |
| `stellar_tx` | Verify the XDR, have the user's Stellar wallet sign it, then submit the signed XDR. |
| `stellar_trustline` | Run sponsored onboarding for the asset, then ask for actions again. |

## submit

```ts theme={null}
pesa.submit(id: string, s: Submission): Promise<TransferView>

type Submission =
  | { kind: "evm_tx"; hash: `0x${string}` }
  | { kind: "stellar_tx"; signed_xdr: string };
```

Submit an EVM transaction hash only after it is mined. The server reads the burn or send from the mined receipt. A submission that does not match the issued action returns `422` with no change.

Pesa's relay wraps a signed Stellar transaction in a fee-bump and submits it, so the user needs no XLM.

## getTransfer

```ts theme={null}
pesa.getTransfer(id: string): Promise<TransferView>
```

```ts theme={null}
interface TransferView {
  id: string;
  route: Route;
  direction: "deposit" | "withdraw" | "send";
  status: Sep24Status;           // whose turn it is
  stage: Stage;                  // the internal state
  amount_in: string;
  amount_out: string;
  amount_fee: string;
  source_chain: string;
  source_address: string;
  dest_chain: string;
  dest_address: string;
  external_transaction_id: string | null;  // the EVM transaction
  stellar_transaction_id: string | null;
  started_at: string;
  updated_at: string;
  completed_at: string | null;
  expires_at: string;
  explorer: { source?: string; destination?: string };
}
```

See [Transfer lifecycle](/chain-abstraction/transfer-lifecycle) for every `stage` and `status`.

## listTransfers

```ts theme={null}
pesa.listTransfers(q?: { before?: string }): Promise<TransferView[]>
```

The owner's transfers, newest first. To get the next page, pass the oldest `started_at` you have as `before` (an ISO date).

## cancel

```ts theme={null}
pesa.cancel(id: string): Promise<TransferView>
```

Allowed in `AWAITING_FUNDS`, `FUNDED` and `AWAITING_SIGNATURE`, before anything irreversible. Otherwise `409` with the stage.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.