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

# Submit signed onboarding transaction

> Submit the user-signed onboarding transaction XDR from `POST /stellar/onboard/build`. The facilitator fee-bumps it (so the user does not need XLM for fees) and submits it to Stellar.



## OpenAPI

````yaml /api-reference/openapi.json post /stellar/onboard/submit
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/onboard/submit:
    post:
      tags:
        - Onboarding
      summary: Submit signed onboarding transaction
      description: >-
        Submit the user-signed onboarding transaction XDR from `POST
        /stellar/onboard/build`. The facilitator fee-bumps it (so the user does
        not need XLM for fees) and submits it to Stellar.
      operationId: postStellarOnboardSubmit
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OnboardSubmitRequest'
      responses:
        '200':
          description: Onboarding transaction submitted successfully.
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                properties:
                  ok:
                    type: boolean
                    description: Always `true` on success.
        '400':
          description: The signed transaction was rejected.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                submit_failed:
                  value:
                    error: submit_failed
                invalid_onboard_tx:
                  value:
                    error: invalid_onboard_tx
        '401':
          description: Invalid or missing API key.
          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:
    OnboardSubmitRequest:
      type: object
      required:
        - publicKey
        - chain
        - signedTxXdr
      properties:
        publicKey:
          allOf:
            - $ref: '#/components/schemas/StellarPublicKey'
          description: G-address of the account being onboarded.
        chain:
          $ref: '#/components/schemas/FacilitatorChain'
        signedTxXdr:
          type: string
          description: >-
            User-signed transaction XDR from the `unsignedTxXdr` field of the
            build response.
    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`).
    StellarPublicKey:
      type: string
      pattern: ^G[A-Z2-7]{55}$
      description: Stellar classic public key (G-address, 56-character StrKey).
    FacilitatorChain:
      type: string
      enum:
        - stellar-testnet
        - stellar-pubnet
      description: Stellar network identifier used in facilitator requests.
  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.

````