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

# Usage and Examples

> Practical SDK usage examples: public endpoints, authenticated calls, error handling, and the end-to-end transaction flow.

This page gathers practical usage examples for `@pagfinance/sdk`.

## Public endpoints (no authentication)

```ts theme={null}
import { PagFinanceClient } from '@pagfinance/sdk';

const client = new PagFinanceClient({
  baseUrl: 'https://app.pag.finance',
  clientId: 'my-app',
  appMeta: { name: 'my-app', version: '1.0.0', domain: 'myapp.com' },
  defaultBlockchain: 'solana',
});

// Accepted crypto configuration
const config = await client.assets.acceptedCryptos();

// Price of an asset in a fiat currency
const price = await client.assets.getAssetPrice({ assetId: 1, fiatCurrency: 'BRL' });

// Validation of a payment code (PIX, boleto, or gift card)
const transfer = await client.payments.validateCode({ code: '00020101...' });
```

## Authenticated calls

Provide the JWT token obtained outside the SDK and call protected endpoints:

```ts theme={null}
client.setToken(tokenJWT);

const me = await client.user.me();
```

## End-to-end transaction flow

The typical payment flow has three steps: quote, creation, and receipt.

<Steps>
  <Step title="Quote">
    Request a quote for the desired payment.

    ```ts theme={null}
    const quote = await client.payments.quote({
      code: '00020101...',
      assetId: 1,
      blockchain: 'solana',
    });
    ```
  </Step>

  <Step title="Create">
    Create the payment from the quote.

    ```ts theme={null}
    const payment = await client.payments.create({
      quoteId: quote.id,
    });
    ```
  </Step>

  <Step title="Submit and track">
    Submit the transaction and fetch the receipt.

    ```ts theme={null}
    await client.payments.submit({ paymentId: payment.id, txHash: '...' });

    const receipt = await client.receipts.get({
      type: 'pix',
      tx: payment.id,
      chain: 'solana',
    });
    ```
  </Step>
</Steps>

<Note>
  The exact fields of each request and response depend on the API contract. See the [API Reference](/en/api-reference/overview) and the [Method Reference](/en/sdks/method-reference) for parameter details.
</Note>

## Error handling

Every failure throws `PagFinanceError`, with messages and field errors already normalized:

```ts theme={null}
import { PagFinanceError } from '@pagfinance/sdk';

try {
  await client.payments.quote(req);
} catch (e) {
  if (e instanceof PagFinanceError) {
    console.error(e.messages, e.fieldErrors, e.httpStatus);
  }
}
```

<Info>
  `PagFinanceError` normalizes the two API response envelopes (`{ success, data }` and `{ ok, error }`) into a single structure with `messages`, `fieldErrors`, `httpStatus`, and `code`.
</Info>

## Runnable example

The package includes a real end-to-end example in `examples/transaction-flow` (quote, creation, and receipt) using a `TOKEN_JWT` environment variable:

```bash theme={null}
pnpm --filter @pagfinance/sdk build

PAGFINANCE_BASE_URL=https://app.pag.finance \
PAGFINANCE_CLIENT_ID=example \
TOKEN_JWT=... \
PAYMENT_CODE='00020101...' \
SENDER_WALLET=7NaNvh... \
npx tsx examples/transaction-flow/index.ts
```

<Tip>
  See the official package on [npm](https://www.npmjs.com/package/@pagfinance/sdk) for the most recent example code.
</Tip>