> ## 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.

# Overview

> Overview of the PagFinance API: base URL, environments, authentication, response envelopes, and common errors.

The PagFinance API lets you integrate cryptocurrency payments converted to local currency (PIX, boleto, and gift card), price quotes, and KYC verification.

<Info>
  The recommended way to consume the API is through the official SDK [@pagfinance/sdk](https://www.npmjs.com/package/@pagfinance/sdk). See the [SDK documentation](/en/sdks/introduction). This reference describes the underlying REST endpoints.
</Info>

## Base URL

The API is exposed through a host that acts as a proxy (for example, a Next.js app or a dedicated BFF). The SDK points to this host via the `baseUrl` option.

<CodeGroup>
  ```bash Production theme={null}
  https://app.pag.finance
  ```

  ```bash Sandbox (BRLP) theme={null}
  https://sandbox.brlp.io
  ```
</CodeGroup>

<Note>
  In the future, the `sandbox.brlp.io` domain will exclusively host the endpoints focused on **BRLP**. Organize your integration with this separation in mind. See the [BRLP](/en/api-reference/brlp) group.
</Note>

## Environments

<CardGroup cols={2}>
  <Card title="Sandbox" icon="flask">
    Testing environment for development and staging. Sandbox base URL.
  </Card>

  <Card title="Production" icon="rocket">
    Production environment with real transactions. Production base URL.
  </Card>
</CardGroup>

## Authentication

The API uses JWT token authentication in the `Authorization` header. The token is obtained through a challenge-response Web3 login flow (SIWS style).

<Steps>
  <Step title="Request challenge">
    `POST /api/auth/challenge` returns a challenge (nonce) for the given address.
  </Step>

  <Step title="Sign">
    The application signs the challenge with the user's wallet.
  </Step>

  <Step title="Verify">
    `POST /api/auth/verify` receives the signature and returns the JWT token.
  </Step>
</Steps>

```http theme={null}
Authorization: Bearer <tokenJWT>
```

<Warning>
  No private key or signing logic lives in the client API. The only proof is the wallet signature, and all validation (nonce, verification, token issuance) happens on the server. See [Authentication](/en/api-reference/authentication).
</Warning>

## Response envelopes

The API can return two envelope formats. The SDK normalizes both automatically.

<CodeGroup>
  ```json Success theme={null}
  {
    "success": true,
    "data": { }
  }
  ```

  ```json Error theme={null}
  {
    "ok": false,
    "error": {
      "code": "VALIDATION_ERROR",
      "messages": ["Error message"],
      "fieldErrors": { "field": "detail" }
    }
  }
  ```
</CodeGroup>

## Common errors

<ResponseField name="400 Bad Request" type="validation error">
  Malformed request or invalid parameters. The `fieldErrors` field details the problems per field.
</ResponseField>

<ResponseField name="401 Unauthorized" type="unauthenticated">
  Missing, expired, or invalid JWT token. Sign in again. The SDK can sign in again automatically (auto-relogin).
</ResponseField>

<ResponseField name="403 Forbidden" type="forbidden">
  The authenticated user does not have permission for the resource, or the required KYC has not been completed.
</ResponseField>

<ResponseField name="404 Not Found" type="not found">
  The resource does not exist (for example, a payment or receipt was not found).
</ResponseField>

<ResponseField name="422 Unprocessable Entity" type="business rule">
  The request is valid but violates a business rule (for example, an amount above the allowed limit).
</ResponseField>

<ResponseField name="429 Too Many Requests" type="rate limit">
  Request limit exceeded. Wait before retrying.
</ResponseField>

<ResponseField name="500 Internal Server Error" type="internal error">
  Unexpected server error. Try again or contact support.
</ResponseField>

## Reference structure

The endpoints are grouped by resource:

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/en/api-reference/authentication">
    Web3 login, tokens, and OTP.
  </Card>

  <Card title="Onramp and Offramp" icon="arrow-right-arrow-left" href="/en/api-reference/onramp-offramp">
    Assets, prices, and conversion between crypto and local currency.
  </Card>

  <Card title="Payments" icon="money-bill-transfer" href="/en/api-reference/payments">
    Payment validation, quoting, creation, and lookup.
  </Card>

  <Card title="BRLP" icon="brazilian-real-sign" href="/en/api-reference/brlp">
    Endpoints focused on BRLP, the future sandbox.brlp.io domain.
  </Card>

  <Card title="KYC" icon="id-card" href="/en/api-reference/kyc">
    Identity verification for individuals and companies.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/en/api-reference/webhooks">
    Payment and KYC event notifications.
  </Card>
</CardGroup>