> ## Documentation Index > Fetch the complete documentation index at: https://docs.troqpay.com/llms.txt > Use this file to discover all available pages before exploring further. # Consultar saldo > Retorna o saldo agregado da conta autenticada, separado em valores brutos, taxas, pendentes, disponíveis, reservados e bloqueados. Todos os valores monetários são strings decimais em BRL. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/balance openapi: 3.1.0 info: title: TroqPay API description: >- API da TroqPay para criar cobranças Pix, ler saldo, solicitar saques em produção e processar eventos por webhook. version: 1.0.0 servers: - url: https://api.troqpay.com description: >- Use a mesma URL-base para teste e produção. O ambiente é definido pela chave utilizada (`trq_test_` ou `trq_live_`). security: - bearerAuth: [] tags: - name: Checkouts description: Criação e consulta de cobranças Pix. - name: Payment Links description: >- Criação, listagem e consulta de links de pagamento a partir de produtos cadastrados. - name: Saldo description: >- Leitura do saldo agregado da conta TroqPay (valores em decimal, todos em BRL). - name: Saques description: Criação e consulta de saques em produção. - name: Webhooks description: Eventos enviados pela TroqPay quando um checkout muda de estado. - name: Status description: Endpoints públicos para verificar disponibilidade da API. paths: /v1/balance: get: tags: - Saldo summary: Consultar saldo description: >- Retorna o saldo agregado da conta autenticada, separado em valores brutos, taxas, pendentes, disponíveis, reservados e bloqueados. Todos os valores monetários são strings decimais em BRL. operationId: getBalance parameters: - $ref: '#/components/parameters/RequestIdHeader' responses: '200': description: Saldo retornado. headers: Request-Id: $ref: '#/components/headers/RequestIdResponseHeader' content: application/json: schema: $ref: '#/components/schemas/Balance' examples: balance: summary: Saldo com valores em BRL value: livemode: false currency: BRL grossAmount: '5430.00' feeAmount: '108.60' pendingAmount: '129.90' availableAmount: '5191.50' reservedAmount: '0.00' blockedAmount: '0.00' '401': $ref: '#/components/responses/Unauthorized' '403': description: >- Conta sem acesso a produção ou chave sem permissão para consultar saldo. headers: Request-Id: $ref: '#/components/headers/RequestIdResponseHeader' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: Chave LIVE em conta não aprovada value: error: type: auth_error code: forbidden message: API key does not have access to live-mode balances requestId: req_4a8b3c1d5e6f2a9b0c1d2e3f missingPermission: summary: Chave sem permissão de leitura de saldo value: error: type: auth_error code: api_key_scope_forbidden message: >- API key does not have permission to access this resource. requestId: req_4a8b3c1d5e6f2a9b0c1d2e3f '429': $ref: '#/components/responses/RateLimited' x-codeSamples: - lang: cURL label: cURL source: |- curl https://api.troqpay.com/v1/balance \ -H "Authorization: Bearer trq_test_xxx" - lang: JavaScript label: JavaScript source: |- const response = await fetch("https://api.troqpay.com/v1/balance", { headers: { "Authorization": "Bearer trq_test_xxx" } }); const balance = await response.json(); components: parameters: RequestIdHeader: name: Request-Id in: header required: false description: >- Identificador opcional fornecido pelo cliente para correlação. A API aceita também `X-Request-Id`. O valor é ecoado de volta no header de resposta `Request-Id`. Se nenhum dos dois é enviado, a API gera `req_<24 hex>`. schema: type: string example: req_4a8b3c1d5e6f2a9b0c1d2e3f headers: RequestIdResponseHeader: description: >- Identificador da requisição. Sempre presente. Ecoa o valor enviado em `Request-Id` ou `X-Request-Id`, ou um identificador gerado pela API no formato `req_<24 hex>`. schema: type: string example: req_4a8b3c1d5e6f2a9b0c1d2e3f schemas: Balance: type: object required: - livemode - currency - grossAmount - feeAmount - pendingAmount - availableAmount - reservedAmount - blockedAmount description: >- Saldo agregado da conta. Todos os valores monetários são strings decimais em BRL. properties: livemode: type: boolean description: '`true` para chaves `trq_live_`; `false` para `trq_test_`.' example: false currency: type: string enum: - BRL example: BRL grossAmount: type: string description: Total bruto recebido (antes das taxas). example: '5430.00' feeAmount: type: string description: Total de taxas cobradas pela TroqPay. example: '108.60' pendingAmount: type: string description: Valores ainda em liquidação. example: '129.90' availableAmount: type: string description: Disponível para saque agora. example: '5191.50' reservedAmount: type: string description: Reservado para saques já solicitados. example: '0.00' blockedAmount: type: string description: Retido por bloqueio operacional ou disputa. example: '0.00' ErrorResponse: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorBody' ErrorBody: type: object required: - type - code - message - requestId description: >- Corpo padronizado de erro da API. As mensagens em `message` chegam em inglês — é o que a API emite literalmente. properties: type: type: string description: Categoria do erro. enum: - auth_error - validation_error - business_error - not_found_error - conflict_error - provider_error - rate_limit_error - internal_error example: validation_error code: type: string description: Código estável para tratar a falha no seu backend. example: invalid_request_body message: type: string description: Mensagem legível do erro (em inglês, literal). example: Number must be greater than 0 requestId: type: string description: Identificador da requisição para logs e investigação. example: req_4a8b3c1d5e6f2a9b0c1d2e3f responses: Unauthorized: description: >- Chave ausente, mal formatada, inválida ou revogada. A API sempre devolve `code: "unauthorized"` em 401. headers: Request-Id: $ref: '#/components/headers/RequestIdResponseHeader' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unauthorized: summary: Bearer ausente ou inválido value: error: type: auth_error code: unauthorized message: invalid or missing bearer token requestId: req_4a8b3c1d5e6f2a9b0c1d2e3f RateLimited: description: Limite de requisições excedido. Faça retry com backoff. headers: Request-Id: $ref: '#/components/headers/RequestIdResponseHeader' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: rateLimited: summary: Limite excedido value: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Please retry with backoff. requestId: req_4a8b3c1d5e6f2a9b0c1d2e3f securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API Key ````