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

# Get contract account state

> Returns on-chain state for a passkey smart-account or policy session-account (C-address). Same response shape as the classic account endpoint. The SDK routes G-addresses to `/stellar/account/:pk` and C-addresses here.



## OpenAPI

````yaml /api-reference/openapi.json get /stellar/contract/{address}
openapi: 3.1.0
info:
  title: Buckspay Facilitator & BFF API
  version: 0.2.0
  description: >-
    HTTP wire contract for the Buckspay SDK. The SDK calls these endpoints
    internally via `@buckspay/relayer`; this reference is for teams building
    their own BFF relay route or calling the facilitator from server-side code.


    All facilitator endpoints require the `x-api-key` header. **The API key is a
    server-side secret - it must only appear in BFF or server-side code and must
    never be shipped to a browser bundle.** Use `createRelayRoute` and
    `createSignerProxyRoute` from `@buckspay/nextjs` to build compliant BFF
    handlers.
servers:
  - url: '{facilitatorUrl}'
    description: >-
      Buckspay facilitator (all endpoints). Set via BUCKSPAY_FACILITATOR_URL on
      the server.
    variables:
      facilitatorUrl:
        default: https://facilitator.buckspay.xyz
        description: Base URL of the Buckspay facilitator service.
security:
  - FacilitatorApiKey: []
tags:
  - name: Relay
    description: >-
      Submit a signed Soroban authorization entry for gasless relaying to the
      Stellar network.
  - name: Fee
    description: >-
      Quote the fee-token amount required for gas-in-token (token gas mode)
      before building the forward() invocation.
  - name: Account State
    description: Read on-chain state for classic G-addresses and contract C-addresses.
  - name: Onboarding
    description: >-
      Build and submit the sponsored onboarding transaction; deploy passkey
      smart-accounts and policy session-accounts.
  - name: Auth
    description: >-
      Signer-proxy for social and email authentication. The BFF forwards these
      requests to the facilitator; provider secrets remain server-side.
  - name: Swap
    description: >-
      Quote a gasless EVM token swap. Requires `swapChain` to be configured in
      the relayer.
paths:
  /stellar/contract/{address}:
    get:
      tags:
        - Account State
      summary: Get contract account state
      description: >-
        Returns on-chain state for a passkey smart-account or policy
        session-account (C-address). Same response shape as the classic account
        endpoint. The SDK routes G-addresses to `/stellar/account/:pk` and
        C-addresses here.
      operationId: getStellarContract
      parameters:
        - name: address
          in: path
          required: true
          description: Contract address (C-address, StrKey encoded).
          schema:
            type: string
            pattern: ^C[A-Z2-7]{55}$
            example: CABC1234...
        - name: chain
          in: query
          required: true
          description: Network to query.
          schema:
            $ref: '#/components/schemas/FacilitatorChain'
      responses:
        '200':
          description: Contract account state returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountState'
        '400':
          description: Invalid address or query parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: Facilitator could not reach Stellar Horizon.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    FacilitatorChain:
      type: string
      enum:
        - stellar-testnet
        - stellar-pubnet
      description: Stellar network identifier used in facilitator requests.
    AccountState:
      type: object
      required:
        - exists
        - hasUsdcTrustline
      properties:
        exists:
          type: boolean
          description: Whether the account exists on-chain.
        hasUsdcTrustline:
          type: boolean
          description: Whether the account has an active USDC trustline.
        xlmBalance:
          type: string
          description: >-
            Native XLM balance as a decimal string (e.g. `10.5000000`). Omitted
            if the facilitator returned `null` or the account does not exist.
        usdcBalance:
          type: string
          description: >-
            USDC balance as a decimal string. Omitted if the account has no
            trustline or the facilitator returned `null`.
      description: >-
        On-chain account state returned by the `/stellar/account/:pk` and
        `/stellar/contract/:address` endpoints. The SDK adapter normalizes the
        facilitator's `nativeBalance` field to `xlmBalance` and strips null
        values.
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: >-
            Machine-readable error code. SDK error codes (e.g.
            `RELAYER_REJECTED`, `SESSION_POLICY_VIOLATION`) or raw facilitator
            codes (e.g. `auth_expired`, `simulation_failed`) depending on
            context.
        message:
          type: string
          description: >-
            Optional human-readable detail. Never log raw upstream messages -
            they may contain addresses or sensitive information.
        details:
          type: object
          description: >-
            Optional structured validation errors (present on BFF-level schema
            failures).
      description: >-
        Error body returned on non-2xx responses. The `error` field maps to a
        `BuckspayErrorCode` or a raw facilitator error string (see
        `mapFacilitatorError` in `@buckspay/relayer`).
  securitySchemes:
    FacilitatorApiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Server-held API key. Injected by the BFF (`createRelayRoute` /
        `createSignerProxyRoute` from `@buckspay/nextjs`). This key must only
        appear in server-side code and must never be shipped to a browser
        bundle.

````