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

# Create transaction

> Initiates a transfer through the custody lifecycle. The transaction
passes through policy evaluation and, if approved, enters the
PENDING_SIGNATURE state. The signing payload must be retrieved
and signed externally using your post-quantum key.




## OpenAPI

````yaml POST /transactions
openapi: 3.1.0
info:
  title: Qustody API
  description: >
    Non-custodial custody and orchestration API for Quantum Chain (post-quantum
    blockchain).

    Provides Fireblocks-like operating model for institutional integrators:

    multi-tenant vault/wallet management, transaction lifecycle with policy
    enforcement,

    external (callback-based) signing, webhook-driven event delivery, and full
    audit trail.
  version: 1.0.0
  contact:
    name: Quantum Chain Platform Team
  license:
    name: LGPL-3.0-or-later
servers:
  - url: '{baseUrl}/v1'
    description: Qustody API
    variables:
      baseUrl:
        default: https://api.qustody.io
security:
  - BearerAPIKey: []
tags:
  - name: health
    description: Liveness and readiness probes
  - name: tenants
    description: Tenant (integrator) management
  - name: vaults
    description: Vault (logical wallet grouping) management
  - name: wallets
    description: Wallet (on-chain address) registration and lookup
  - name: transactions
    description: Transaction lifecycle – create, sign, approve, reject, query
  - name: assets
    description: Supported asset registry
  - name: webhooks
    description: Webhook endpoint management
  - name: sso
    description: Single Sign-On (OIDC and SAML) authentication
  - name: tokens
    description: Token Management — Beta / Proposed.
paths:
  /transactions:
    post:
      tags:
        - transactions
      summary: Create a new transfer
      description: |
        Initiates a transfer through the custody lifecycle. The transaction
        passes through policy evaluation and, if approved, enters the
        PENDING_SIGNATURE state. The signing payload must be retrieved
        and signed externally using your post-quantum key.
      operationId: createTransfer
      parameters:
        - $ref: '#/components/parameters/idempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTransferRequest'
      responses:
        '201':
          description: Transaction created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transaction'
components:
  parameters:
    idempotencyKey:
      name: Idempotency-Key
      in: header
      schema:
        type: string
      description: Idempotency key for safe retries (required for POST/PUT)
  schemas:
    CreateTransferRequest:
      type: object
      required:
        - sourceWalletId
        - destinationAddr
        - assetId
        - amount
      properties:
        sourceWalletId:
          type: string
          format: uuid
        destinationAddr:
          type: string
          pattern: ^0x[a-fA-F0-9]{40}$
        assetId:
          type: string
          format: uuid
        amount:
          type: string
          description: Wei-denominated amount as string
        externalId:
          type: string
          description: Client-provided idempotency/correlation ID
        note:
          type: string
        metadata:
          type: object
          additionalProperties:
            type: string
    Transaction:
      type: object
      required:
        - id
        - tenantId
        - sourceVaultId
        - sourceWalletId
        - destinationAddr
        - assetId
        - amount
        - status
        - createdAt
      properties:
        id:
          type: string
          format: uuid
        tenantId:
          type: string
          format: uuid
        externalId:
          type: string
        sourceVaultId:
          type: string
          format: uuid
        sourceWalletId:
          type: string
          format: uuid
        destinationAddr:
          type: string
        assetId:
          type: string
          format: uuid
        amount:
          type: string
          description: Wei-denominated amount as string
        fee:
          type: string
        gasLimit:
          type: integer
          format: uint64
        nonce:
          type: integer
          format: uint64
        status:
          type: string
          enum:
            - SUBMITTED
            - QUEUED
            - PENDING_AML_SCREENING
            - PENDING_AUTHORIZATION
            - APPROVED
            - REJECTED
            - PENDING_SIGNATURE
            - SIGNED
            - BROADCASTING
            - CONFIRMING
            - COMPLETED
            - FAILED
            - CANCELLED
            - BLOCKED
        failureReason:
          type: string
        chainTxHash:
          type: string
        blockNumber:
          type: integer
          format: uint64
        confirmations:
          type: integer
          format: uint64
        note:
          type: string
        metadata:
          type: object
          additionalProperties:
            type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        broadcastAt:
          type: string
          format: date-time
        confirmedAt:
          type: string
          format: date-time
  securitySchemes:
    BearerAPIKey:
      type: http
      scheme: bearer
      description: 'API key authentication. Format: `Bearer {key_id}:{secret}`'

````