> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Create an atomic batch of Transactions (v2) > Executes direct and hold transactions once, in explicit increasing order, as one all-or-none accounting decision. The response preserves that order. The decoded body must be smaller than 1 MiB; the configured cardinality is 1-50, aggregate input legs are limited to 1,000, and post-fee work is limited to 100 postings and 150 balance snapshots. The internal idempotency/recovery batch identifier is not exposed; there is no batch query endpoint. ## OpenAPI ````yaml /pt/openapi/v3-current/ledger.yaml post /v2/transactions/batch openapi: 3.1.0 info: title: Midaz Ledger API version: 4.0.0 servers: - url: / security: [] tags: - name: Account Block Exceptions (v2) - name: Account Types (v1) - name: Account Types (v2) - name: Accounts (v1) - name: Accounts (v2) - name: Asset Rates (v1) - name: Assets (v1) - name: Assets (v2) - name: Balances (v1) - name: Balances (v2) - name: Billing Calculate (v2) - name: Billing Packages (v2) - name: Composition (v2) - name: Dashboard (v1) - name: Dashboard (v2) - name: Encryption (v2) - name: Fees (v2) - name: Holders (v2) - name: Instruments (v2) - name: Ledgers (v1) - name: Ledgers (v2) - name: Metadata Indexes (v1) - name: Metadata Indexes (v2) - name: Operation Routes (v1) - name: Operation Routes (v2) - name: Operations (v1) - name: Operations (v2) - name: Organizations (v1) - name: Organizations (v2) - name: Packages (v2) - name: Portfolios (v1) - name: Portfolios (v2) - name: Protection (v2) - name: Segments (v1) - name: Segments (v2) - name: Transaction Routes (v1) - name: Transaction Routes (v2) - name: Transactions (v1) - name: Transactions (v2) paths: /v2/transactions/batch: post: tags: - Transactions (v2) summary: Create an atomic batch of Transactions (v2) description: >- Executes direct and hold transactions once, in explicit increasing order, as one all-or-none accounting decision. The response preserves that order. The decoded body must be smaller than 1 MiB; the configured cardinality is 1-50, aggregate input legs are limited to 1,000, and post-fee work is limited to 100 postings and 150 balance snapshots. The internal idempotency/recovery batch identifier is not exposed; there is no batch query endpoint. operationId: createAtomicTransactionBatchV2 parameters: - description: >- Idempotency key to safely retry the atomic batch; an identical retry returns the original ordered response in: header name: X-Idempotency schema: description: >- Idempotency key to safely retry the atomic batch; an identical retry returns the original ordered response type: string - description: Idempotency slot TTL in seconds (default 300) in: header name: X-TTL schema: description: Idempotency slot TTL in seconds (default 300) type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateAtomicTransactionBatchV2Request' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/CreateAtomicTransactionBatchV2Response' description: Created headers: X-Idempotency-Replayed: schema: type: string '422': content: application/problem+json: schema: $ref: '#/components/schemas/Error' description: Unprocessable Entity '500': content: application/problem+json: schema: $ref: '#/components/schemas/Error' description: Internal Server Error default: content: application/problem+json: schema: $ref: '#/components/schemas/Error' description: Error security: - BearerAuth: [] components: schemas: CreateAtomicTransactionBatchV2Request: additionalProperties: false properties: transactions: description: >- Direct or hold transactions with unique consecutive order. All items succeed atomically or none is applied. items: $ref: '#/components/schemas/CreateAtomicTransactionBatchV2ItemRequest' maxItems: 50 minItems: 1 type: array required: - transactions type: object CreateAtomicTransactionBatchV2Response: additionalProperties: false properties: transactions: description: Created transactions in increasing logical order. items: $ref: '#/components/schemas/AtomicTransactionBatchV2Transaction' type: array required: - transactions type: object Error: additionalProperties: true properties: code: description: >- Stable, machine-readable domain error code scoped to the emitting service (format: -NNNN). type: string detail: description: >- A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string errors: description: Optional list of individual error details items: $ref: '#/components/schemas/ErrorDetail' type: - array - 'null' instance: description: >- A URI reference that identifies the specific occurrence of the problem. examples: - https://example.com/error-log/abc123 format: uri type: string status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: >- A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string upstream: $ref: '#/components/schemas/Upstream' description: >- RFC 9457 extension member: the error a proxied third-party provider reported. Absent unless the emitting service explicitly surfaced one. type: object CreateAtomicTransactionBatchV2ItemRequest: additionalProperties: false properties: accountBlockExceptionId: description: >- Single-use account-block exception identifier. Authorizes one debit of an exact amount out of a blocked source account, and is consumed on use. Rejected on the hold action. examples: - 00000000-0000-0000-0000-000000000000 format: uuid type: string action: description: Transaction action. enum: - direct - hold type: string amount: type: string asset: type: string code: type: string credits: items: $ref: '#/components/schemas/V2LegInput' maxItems: 500 minItems: 1 type: array debits: items: $ref: '#/components/schemas/V2LegInput' maxItems: 500 minItems: 1 type: array description: type: string metadata: additionalProperties: {} type: object operationRouteId: examples: - 00000000-0000-0000-0000-000000000000 format: uuid type: string order: description: One-based logical execution order. format: int64 minimum: 1 type: integer routeId: examples: - 00000000-0000-0000-0000-000000000000 format: uuid type: string skip: $ref: '#/components/schemas/TransactionSkip' required: - action - order - asset - amount - debits - credits type: object AtomicTransactionBatchV2Transaction: additionalProperties: false properties: amount: examples: - '1500' minimum: 0 type: - string - 'null' assetCode: examples: - BRL maxLength: 10 minLength: 2 type: string createdAt: examples: - '2021-01-01T00:00:00Z' format: date-time type: string credit: examples: - - '@person2' items: type: string type: - array - 'null' debit: examples: - - '@person1' items: type: string type: - array - 'null' deletedAt: examples: - '2021-01-01T00:00:00Z' format: date-time type: - string - 'null' description: examples: - Transaction description maxLength: 256 type: string feesSkipped: examples: - false type: boolean groupId: examples: - 00000000-0000-0000-0000-000000000000 format: uuid type: string id: examples: - 00000000-0000-0000-0000-000000000000 format: uuid type: string ledgerId: examples: - 00000000-0000-0000-0000-000000000000 format: uuid type: string metadata: additionalProperties: {} description: >- Additional custom attributes. The ledger writes three fee keys on this field itself and reserves all three: feeApplied is the string true when the fee engine actually charged this transaction; packageAppliedID is the identifier of the fee package the engine applied, written when that package charged a fee or recorded an exemption, and absent when a package matched but priced nothing, for instance because the amount fell outside its bounds; feeExemption is a string holding a JSON object with exempt, reason and message, present when every account on one side of the transaction is exempt from fees, which is how a caller tells an exemption apart from no package having matched; a transaction recorded before v4.1.1 may carry feeExemption as that object itself instead of the string, so a reader must accept both shapes. A request body carrying feeApplied, packageAppliedID or feeExemption is refused with 400 naming the offending key, on every body that carries transaction metadata: a create, a metadata update and a fee estimate. So a value present here is always the ledger's own word about the charge and never one a caller supplied. feeLeg, on operation metadata, is reserved the same way. Transaction-level metadata is additive, so caller-supplied keys on this field are preserved alongside the ledger keys. type: object operations: items: $ref: '#/components/schemas/OperationV2' type: - array - 'null' order: description: Logical order used to execute this transaction. format: int64 minimum: 1 type: integer organizationId: examples: - 00000000-0000-0000-0000-000000000000 format: uuid type: string parentTransactionId: examples: - 00000000-0000-0000-0000-000000000000 format: uuid type: string routeId: examples: - 00000000-0000-0000-0000-000000000000 format: uuid type: string status: $ref: '#/components/schemas/TransactionStatus' tracerSkipped: examples: - false type: boolean updatedAt: examples: - '2021-01-01T00:00:00Z' format: date-time type: string required: - order - id - description - status - amount - assetCode - debit - credit - ledgerId - organizationId - feesSkipped - tracerSkipped - createdAt - updatedAt - deletedAt - operations type: object ErrorDetail: additionalProperties: false properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object Upstream: additionalProperties: false properties: code: description: The upstream provider's own error code, verbatim. examples: - E4001 type: string message: description: >- The upstream provider's own error message, verbatim (bounded, never its raw response body). examples: - account not found at provider type: string type: object V2LegInput: additionalProperties: false description: >- One leg of a transaction side. Fill EXACTLY ONE value expression per leg: `amount` for an explicit value, or `share` for a percentage of the transaction total. A leg carrying both, or neither, is rejected. `balanceKey` optionally selects one of the account's balances; when omitted, the `default` balance is used. properties: alias: description: >- The leg's account alias. Accepts letters, digits and the characters @ : _ and -, or an external account alias spelled @external/ followed by the uppercase asset code. Any other spelling is refused with 400 before the transaction is calculated. examples: - '@person1' type: string amount: type: string balanceKey: description: >- Optional balance key for this leg. When omitted, the transaction uses the account's default balance. examples: - food maxLength: 100 type: string description: maxLength: 256 type: string ledgerId: examples: - 00000000-0000-0000-0000-000000000000 format: uuid type: string operationRouteId: examples: - 00000000-0000-0000-0000-000000000000 format: uuid type: string organizationId: examples: - 00000000-0000-0000-0000-000000000000 format: uuid type: string share: $ref: '#/components/schemas/V2ShareInput' required: - alias - organizationId - ledgerId type: object TransactionSkip: additionalProperties: false properties: fees: examples: - false type: boolean tracer: examples: - false type: boolean type: object OperationV2: additionalProperties: false properties: accountAlias: examples: - '@person1' maxLength: 256 type: string accountId: examples: - 00000000-0000-0000-0000-000000000000 format: uuid type: string amount: $ref: '#/components/schemas/OperationAmount' assetCode: examples: - BRL maxLength: 10 minLength: 2 type: string balance: $ref: '#/components/schemas/OperationBalance' balanceAffected: examples: - true format: boolean type: boolean balanceAfter: $ref: '#/components/schemas/OperationBalance' balanceId: examples: - 00000000-0000-0000-0000-000000000000 format: uuid type: string balanceKey: examples: - asset-freeze maxLength: 100 type: string createdAt: examples: - '2021-01-01T00:00:00Z' format: date-time type: string deletedAt: examples: - '2021-01-01T00:00:00Z' format: date-time type: - string - 'null' description: examples: - Credit card operation maxLength: 256 type: string direction: examples: - debit maxLength: 50 type: string id: examples: - 00000000-0000-0000-0000-000000000000 format: uuid type: string ledgerId: examples: - 00000000-0000-0000-0000-000000000000 format: uuid type: string metadata: additionalProperties: {} description: >- Additional custom attributes. The ledger reserves the feeLeg key on this field and writes it itself: feeLeg is the string true on every operation the fee engine created, and never appears on an operation the caller authored, because a request body that carries the key is refused rather than silently stripped. So a client names a fee movement from the ledger mark instead of inferring one from account names or from the caller metadata. Caller-supplied keys on an operation are returned as sent on a transaction no fee package was applied to; once a package is applied the engine rebuilds every movement of both sides, including when it prices the transaction at zero because every account is exempt, and the rebuilt movements carry only the ledger keys, so do not rely on a per-movement caller reference surviving a payment a fee package was applied to. type: object organizationId: examples: - 00000000-0000-0000-0000-000000000000 format: uuid type: string routeCode: examples: - ROUTE-001 maxLength: 100 type: string routeDescription: examples: - Settlement route for service charges maxLength: 250 type: string routeId: examples: - 00000000-0000-0000-0000-000000000000 format: uuid type: string status: $ref: '#/components/schemas/OperationStatus' transactionId: examples: - 00000000-0000-0000-0000-000000000000 format: uuid type: string type: examples: - DEBIT maxLength: 50 type: string updatedAt: examples: - '2021-01-01T00:00:00Z' format: date-time type: string required: - id - transactionId - description - type - assetCode - amount - balance - balanceAfter - status - accountId - accountAlias - balanceKey - balanceId - organizationId - ledgerId - balanceAffected - createdAt - updatedAt - deletedAt - metadata type: object TransactionStatus: additionalProperties: false properties: code: examples: - ACTIVE maxLength: 100 type: string description: examples: - Active status maxLength: 256 type: - string - 'null' required: - code - description type: object V2ShareInput: additionalProperties: false properties: percentage: examples: - 60 format: int64 maximum: 100 minimum: 1 type: integer percentageOfPercentage: examples: - 50 format: int64 maximum: 100 minimum: 0 type: integer required: - percentage type: object OperationAmount: additionalProperties: false properties: value: examples: - '1500' minimum: 0 type: - string - 'null' required: - value type: object OperationBalance: additionalProperties: false properties: available: examples: - '1500' minimum: 0 type: - string - 'null' onHold: examples: - '500' minimum: 0 type: - string - 'null' overdraftUsed: examples: - '130' minimum: 0 type: string version: examples: - 2 format: int64 minimum: 0 type: - integer - 'null' required: - available - onHold - version - overdraftUsed type: object OperationStatus: additionalProperties: false properties: code: examples: - ACTIVE maxLength: 100 type: string description: examples: - Active status maxLength: 256 type: - string - 'null' required: - code - description type: object securitySchemes: BearerAuth: bearerFormat: JWT description: JWT bearer token issued by the identity provider. scheme: bearer type: http ````