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

# View your USD balance estimate and payout allowance

> See estimated USD balances and your business's payout allowance.

**Required scope:** `balances:read`

Requires balances:read. Exact balances remain in their original currencies; USD values are indicative estimates, not a quote or permission to pay. valuationStatus=partial means some balances could not be valued: null totals are unavailable, not zero, and valuedSubtotalUsd covers only valued balances. Estimates cover the selected profile. payoutAllowance is shared by profiles belonging to the same business; it shows the per-payment cap, monthly usage, reservations, remaining allowance and reset time. Null limits mean unlimited; zero prevents new positive payouts when enforcementEnabled is true. enforcementEnabled tells you whether these USD limits are currently applied. Payment creation checks current balance, allowance and eligibility again. Responses use Cache-Control: private, no-store.


## OpenAPI

````yaml /openapi/public.yaml get /v1/balances/summary
openapi: 3.1.0
info:
  title: Ledig payments API
  version: 0.1.0
  description: >-
    Use the Ledig payments engine to receive funds, view balances, convert
    currencies and send payments.


    Choose Sandbox to test your integration or Live for production payments.
    Each endpoint explains the fields, permissions and errors you need to
    handle.


    Sign API requests with your business API key and HMAC-SHA256. Endpoints
    listing BearerAuth also accept a user access token. Follow
    https://docs.ledig.io/auth/authentication to sign your requests.
  contact:
    name: Ledig
    email: support@ledig.io
    url: https://docs.ledig.io
servers:
  - url: https://api-sandbox.ledig.io
    description: Sandbox
  - url: https://api.ledig.io
    description: Live
security:
  - LedigApiKey: []
    LedigTimestamp: []
    LedigSignature: []
tags:
  - name: Managed businesses
    description: Onboarding for businesses you manage.
  - name: System
    description: Health and availability.
  - name: Balances
    description: Your available and reserved funds by currency.
  - name: Currencies and rates
    description: Supported currencies, networks and indicative rates.
  - name: Funding accounts
    description: Fiat accounts that receive customer deposits.
  - name: Deposit wallets
    description: Crypto addresses that receive customer deposits.
  - name: Recipients
    description: Saved payout destinations.
  - name: Ledig businesses
    description: Find a business before paying through the Ledig network.
  - name: Payment options
    description: Available payout methods, fees and limits.
  - name: Quotes
    description: Confirm rates, fees and amounts before sending.
  - name: Transfers
    description: Start and track conversions and payments.
  - name: Transactions
    description: Customer transaction history.
paths:
  /v1/balances/summary:
    get:
      tags:
        - Balances
      summary: View your USD balance estimate and payout allowance
      description: See estimated USD balances and your business's payout allowance.
      operationId: getEstimatedUsdBalanceSummary
      parameters:
        - name: X-Request-ID
          in: header
          required: false
          schema:
            type: string
        - name: x-ledig-business-id
          in: header
          required: false
          schema:
            type: string
            pattern: ^[A-Za-z0-9][A-Za-z0-9_-]{0,199}$
          description: The business whose balances you are authorised to view.
        - name: x-ledig-acting-business-id
          in: header
          required: false
          schema:
            type: string
            pattern: ^[A-Za-z0-9][A-Za-z0-9_-]{0,199}$
          description: >-
            Your institution when acting for a managed business. It must match
            your credentials; use HMAC v2.
        - name: x-ledig-profile-id
          in: header
          required: false
          schema:
            type: string
            pattern: ^[A-Za-z0-9][A-Za-z0-9_-]{0,199}$
          description: >-
            The profile whose balances you are authorised to view. Profiles in
            the same business share its payout allowance.
      responses:
        '200':
          description: Your estimated USD balances and current payout allowance.
          headers:
            Cache-Control:
              schema:
                type: string
                const: private, no-store
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                  - status
                  - data
                properties:
                  status:
                    type: string
                    const: success
                  data:
                    $ref: '#/components/schemas/EstimatedUsdBalanceSummary'
              example:
                status: success
                data:
                  profileId: profile_example
                  valuationCurrency: USD
                  estimated: true
                  asOf: '2026-10-26T12:00:00.000Z'
                  balanceScope: profile
                  valuationStatus: complete
                  estimatedTotalUsd: '1000.00'
                  estimatedAvailableUsd: '900.00'
                  estimatedReservedUsd: '100.00'
                  valuedSubtotalUsd:
                    total: '1000.00'
                    available: '900.00'
                    reserved: '100.00'
                  balances:
                    - currency: NGN
                      available: '1350000'
                      reserved: '150000'
                      total: '1500000'
                      estimatedTotalUsd: '1000.00'
                      estimatedAvailableUsd: '900.00'
                      estimatedReservedUsd: '100.00'
                      valuationStatus: available
                      rate:
                        baseCurrency: USD
                        quoteCurrency: NGN
                        bid: '1500'
                        asOf: '2026-10-26T11:59:00.000Z'
                        expiresAt: '2026-10-26T12:04:00.000Z'
                  payoutAllowance:
                    scope: parent_business
                    segment: standard
                    transactionLimitUsd: '10000'
                    monthlyLimitUsd: '100000'
                    usedUsd: '20000'
                    reservedUsd: '5000'
                    remainingUsd: '75000'
                    periodStart: '2026-10-01T00:00:00.000Z'
                    resetsAt: '2026-11-01T00:00:00.000Z'
                    timezone: UTC
                    enforcementEnabled: false
        '400':
          description: Invalid request, unknown query parameter or malformed identifier.
          headers:
            Cache-Control:
              schema:
                type: string
                const: private, no-store
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                  - status
                  - code
                  - message
                properties:
                  status:
                    type: string
                    const: error
                  code:
                    type: string
                  message:
                    type: string
              example:
                status: error
                code: BAD_REQUEST
                message: >-
                  Malformed request, unknown query parameter, invalid
                  identifier, amount, version or justification.
        '401':
          description: Valid authentication is required.
          headers:
            Cache-Control:
              schema:
                type: string
                const: private, no-store
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                  - status
                  - code
                  - message
                properties:
                  status:
                    type: string
                    const: error
                  code:
                    type: string
                  message:
                    type: string
              example:
                status: error
                code: UNAUTHORIZED
                message: Valid authentication is required.
        '403':
          description: >-
            Your credentials lack balances:read, balance access or permission to
            view this business or profile.
          headers:
            Cache-Control:
              schema:
                type: string
                const: private, no-store
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                  - status
                  - code
                  - message
                properties:
                  status:
                    type: string
                    const: error
                  code:
                    type: string
                  message:
                    type: string
              example:
                status: error
                code: FORBIDDEN
                message: >-
                  Missing balances:read permission, balances service access or
                  ownership of the selected business/profile.
        '404':
          description: The selected business or profile was not found.
          headers:
            Cache-Control:
              schema:
                type: string
                const: private, no-store
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                  - status
                  - code
                  - message
                properties:
                  status:
                    type: string
                    const: error
                  code:
                    type: string
                  message:
                    type: string
              example:
                status: error
                code: NOT_FOUND
                message: The selected profile or parent business was not found.
        '429':
          description: Request allowance exhausted.
          headers:
            Cache-Control:
              schema:
                type: string
                const: private, no-store
            Retry-After:
              schema:
                type: integer
                minimum: 1
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                  - status
                  - code
                  - message
                properties:
                  status:
                    type: string
                    const: error
                  code:
                    type: string
                  message:
                    type: string
              example:
                status: error
                code: RATE_LIMITED
                message: Request allowance exhausted.
        '500':
          description: The balance summary could not be retrieved.
          headers:
            Cache-Control:
              schema:
                type: string
                const: private, no-store
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                  - status
                  - code
                  - message
                properties:
                  status:
                    type: string
                    const: error
                  code:
                    type: string
                  message:
                    type: string
              example:
                status: error
                code: INTERNAL_ERROR
                message: An unexpected authoritative-store operation failed.
        '503':
          description: >-
            The balance summary is temporarily unavailable.
            RATE_AUTHORITATIVE_STORE_UNAVAILABLE means the indicative rates
            could not be retrieved; an outage does not mean your balance is
            zero.
          headers:
            Cache-Control:
              schema:
                type: string
                const: private, no-store
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                  - status
                  - code
                  - message
                properties:
                  status:
                    type: string
                    const: error
                  code:
                    type: string
                  message:
                    type: string
              example:
                status: error
                code: PROVIDER_UNAVAILABLE
                message: >-
                  An authoritative dependency is unavailable. No successful
                  empty fallback is returned. Indicative rate-store failures use
                  RATE_AUTHORITATIVE_STORE_UNAVAILABLE.
      security:
        - BearerAuth: []
        - LedigApiKey: []
          LedigTimestamp: []
          LedigSignature: []
      x-codeSamples:
        - lang: javascript
          label: Node.js
          source: >-
            import { createHmac } from "node:crypto";


            // Node.js 18+. Set credentials and resource values on your server.

            function required(name) {
              const value = process.env[name];
              if (!value) throw new Error(`Set ${name} before running this example.`);
              return value;
            }


            const baseUrl = process.env.LEDIG_API_BASE_URL ??
            "https://api-sandbox.ledig.io";

            const method = "GET";

            const path = `/v1/balances/summary`;

            const pathWithQuery = path;

            const rawBody = "";

            const headers = { "Accept": "application/json" };

            const timestamp = Math.floor(Date.now() / 1000).toString();

            const payload =
            `${timestamp}.${method}.${pathWithQuery}.${rawBody}`;

            headers["x-ledig-key"] = required("LEDIG_API_KEY");

            headers["x-ledig-timestamp"] = timestamp;

            headers["x-ledig-signature"] = "v1=" + createHmac("sha256",
            required("LEDIG_API_SECRET"))
              .update(payload).digest("base64");

            const response = await fetch(`${baseUrl}${pathWithQuery}`, {
              method,
              headers,
            });

            const result = await response.json();

            // Use result in your application; do not log credentials or upload
            links.

            console.log(response.status);
components:
  schemas:
    EstimatedUsdBalanceSummary:
      type: object
      additionalProperties: false
      required:
        - profileId
        - valuationCurrency
        - estimated
        - asOf
        - balanceScope
        - valuationStatus
        - estimatedTotalUsd
        - estimatedAvailableUsd
        - estimatedReservedUsd
        - valuedSubtotalUsd
        - balances
        - payoutAllowance
      properties:
        profileId:
          type: string
          pattern: ^[A-Za-z0-9][A-Za-z0-9_-]{0,199}$
        valuationCurrency:
          type: string
          const: USD
        estimated:
          type: boolean
          const: true
        asOf:
          type: string
          format: date-time
        balanceScope:
          type: string
          const: profile
        valuationStatus:
          type: string
          enum:
            - complete
            - partial
        estimatedTotalUsd:
          anyOf:
            - type: string
              pattern: ^-?(?:0|[1-9]\d*)(?:\.\d{1,2})?$
              description: Signed estimated USD value, rounded to cents.
            - type: 'null'
        estimatedAvailableUsd:
          anyOf:
            - type: string
              pattern: ^-?(?:0|[1-9]\d*)(?:\.\d{1,2})?$
              description: Signed estimated USD value, rounded to cents.
            - type: 'null'
        estimatedReservedUsd:
          anyOf:
            - type: string
              pattern: ^-?(?:0|[1-9]\d*)(?:\.\d{1,2})?$
              description: Signed estimated USD value, rounded to cents.
            - type: 'null'
        valuedSubtotalUsd:
          type: object
          additionalProperties: false
          required:
            - total
            - available
            - reserved
          properties:
            total:
              type: string
              pattern: ^-?(?:0|[1-9]\d*)(?:\.\d{1,2})?$
              description: >-
                Signed estimated USD value for balances that could be valued,
                rounded to cents.
            available:
              type: string
              pattern: ^-?(?:0|[1-9]\d*)(?:\.\d{1,2})?$
              description: >-
                Signed estimated USD value for balances that could be valued,
                rounded to cents.
            reserved:
              type: string
              pattern: ^-?(?:0|[1-9]\d*)(?:\.\d{1,2})?$
              description: >-
                Signed estimated USD value for balances that could be valued,
                rounded to cents.
        balances:
          type: array
          items:
            $ref: '#/components/schemas/EstimatedUsdCurrencyBalance'
        payoutAllowance:
          $ref: '#/components/schemas/CustomerPayoutUsdAllowance'
    EstimatedUsdCurrencyBalance:
      type: object
      additionalProperties: false
      required:
        - currency
        - available
        - reserved
        - total
        - estimatedTotalUsd
        - estimatedAvailableUsd
        - estimatedReservedUsd
        - valuationStatus
        - rate
      properties:
        currency:
          type: string
          pattern: ^[A-Z0-9]{2,12}$
        available:
          type: string
          pattern: ^-?(?:0|[1-9]\d*)(?:\.\d{1,18})?$
          description: >-
            Exact balance decimal string. Negative balances remain negative in
            the estimate.
        reserved:
          type: string
          pattern: ^-?(?:0|[1-9]\d*)(?:\.\d{1,18})?$
          description: >-
            Exact balance decimal string. Negative balances remain negative in
            the estimate.
        total:
          type: string
          pattern: ^-?(?:0|[1-9]\d*)(?:\.\d{1,18})?$
          description: >-
            Exact balance decimal string. Negative balances remain negative in
            the estimate.
        estimatedTotalUsd:
          anyOf:
            - type: string
              pattern: ^-?(?:0|[1-9]\d*)(?:\.\d{1,2})?$
              description: Signed estimated USD value, rounded to cents.
            - type: 'null'
        estimatedAvailableUsd:
          anyOf:
            - type: string
              pattern: ^-?(?:0|[1-9]\d*)(?:\.\d{1,2})?$
              description: Signed estimated USD value, rounded to cents.
            - type: 'null'
        estimatedReservedUsd:
          anyOf:
            - type: string
              pattern: ^-?(?:0|[1-9]\d*)(?:\.\d{1,2})?$
              description: Signed estimated USD value, rounded to cents.
            - type: 'null'
        valuationStatus:
          type: string
          enum:
            - available
            - missing
            - stale
            - invalid
            - ambiguous
        rate:
          anyOf:
            - $ref: '#/components/schemas/EstimatedUsdRate'
            - type: 'null'
    CustomerPayoutUsdAllowance:
      type: object
      additionalProperties: false
      required:
        - scope
        - segment
        - transactionLimitUsd
        - monthlyLimitUsd
        - usedUsd
        - reservedUsd
        - remainingUsd
        - periodStart
        - resetsAt
        - timezone
        - enforcementEnabled
      properties:
        scope:
          type: string
          const: parent_business
        segment:
          type: string
          enum:
            - standard
            - institutional
        transactionLimitUsd:
          anyOf:
            - type: string
              pattern: ^(?:0|[1-9]\d{0,27})(?:\.\d{1,2})?$
            - type: 'null'
          description: >-
            The USD principal cap per payment. Null means unlimited; zero
            prevents new positive payouts when enforcementEnabled is true.
        monthlyLimitUsd:
          anyOf:
            - type: string
              pattern: ^(?:0|[1-9]\d{0,27})(?:\.\d{1,2})?$
            - type: 'null'
          description: >-
            The monthly USD principal cap. Null means unlimited; zero prevents
            new positive payouts when enforcementEnabled is true.
        usedUsd:
          type: string
          pattern: ^(?:0|[1-9]\d*)(?:\.\d{1,2})?$
          description: >-
            Exact nonnegative USD decimal string. Use decimal arithmetic for
            financial calculations.
        reservedUsd:
          type: string
          pattern: ^(?:0|[1-9]\d*)(?:\.\d{1,2})?$
          description: >-
            Exact nonnegative USD decimal string. Use decimal arithmetic for
            financial calculations.
        remainingUsd:
          anyOf:
            - type: string
              pattern: ^(?:0|[1-9]\d*)(?:\.\d{1,2})?$
              description: >-
                Exact nonnegative USD decimal string. Use decimal arithmetic for
                financial calculations.
            - type: 'null'
        periodStart:
          type: string
          format: date-time
        resetsAt:
          type: string
          format: date-time
        timezone:
          type: string
          const: UTC
        enforcementEnabled:
          type: boolean
          description: >-
            Whether these USD payout limits are currently applied when creating
            a payment.
    EstimatedUsdRate:
      type: object
      additionalProperties: false
      required:
        - baseCurrency
        - quoteCurrency
        - bid
        - asOf
        - expiresAt
      properties:
        baseCurrency:
          type: string
          const: USD
        quoteCurrency:
          type: string
          pattern: ^[A-Z0-9]{2,12}$
        bid:
          type: string
          pattern: ^(?!0(?:\.0+)?$)(?:0|[1-9]\d{0,39})(?:\.\d{1,18})?$
          description: >-
            An indicative bid for the returned baseCurrency/quoteCurrency pair,
            with up to 18 decimal places. Create a quote for an executable rate.
        asOf:
          type: string
          format: date-time
        expiresAt:
          type:
            - string
            - 'null'
          format: date-time
  securitySchemes:
    LedigApiKey:
      type: apiKey
      in: header
      name: x-ledig-key
      description: >-
        Your business API key ID. Keep its secret on your server and use that
        secret to sign each request.
    LedigTimestamp:
      type: apiKey
      in: header
      name: x-ledig-timestamp
      description: The current Unix timestamp in seconds, used in the signed request.
    LedigSignature:
      type: apiKey
      in: header
      name: x-ledig-signature
      description: >-
        The request's HMAC-SHA256 signature. Use the v1= prefix for supported
        own-business requests, or v2= when acting for a managed business with
        signed business-selection headers. Follow the authentication guide to
        construct and sign the exact request.
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        A user access token from sign-in. Send Authorization: Bearer followed by
        the token. Use this only on endpoints that list BearerAuth.

````

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