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

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://developers.fireblocks.com/feedback

```json
{
  "path": "/api-reference/payments--payout/create-a-payout-instruction-set",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# Create a payout instruction set

> **Note:** The reference content in this section documents the Payments
Engine endpoint. The Payments Engine endpoints include APIs available only
for customers with Payments Engine enabled on their accounts.

These endpoints are currently in beta and might be subject to
changes.

If you want to learn more about Fireblocks Payments Engine, please
contact your Fireblocks Customer Success Manager or email
CSM@fireblocks.com.

**Create a payout instruction set.**

A payout instruction set is a set of instructions for distributing payments
from a single payment account to a list of payee accounts.

The instruction set defines:

- the payment account and its account type (vault, exchange, or fiat).
- the account type (vault account, exchange account, whitelisted address,
  network connection, fiat account, or merchant account), the amount, and the
  asset of payment for each payee account.

Learn more about Fireblocks Payments - Payouts in the following
[guide](https://developers.fireblocks.com/docs/create-payouts).

Endpoint Permission: Admin, Non-Signing Admin.




## OpenAPI

````yaml https://docs.fireblocks.com/api/v1/swagger.yaml post /payments/payout
openapi: 3.0.0
info:
  title: Fireblocks API
  description: >
    Fireblocks provides a suite of applications to manage digital asset
    operations and a complete development platform to build your business on the
    blockchain.


    - Visit our website for more information: [Fireblocks
    Website](https://fireblocks.com)

    - Visit our developer docs: [Fireblocks
    DevPortal](https://developers.fireblocks.com)
  version: 1.6.2
  contact:
    email: developers@fireblocks.com
servers:
  - url: https://api.fireblocks.io/v1
    description: Fireblocks Production Environment Base URL
  - url: https://sandbox-api.fireblocks.io/v1
    description: Fireblocks Sandbox Environment Base URL
security: []
paths:
  /payments/payout:
    post:
      tags:
        - Payments - Payout
      summary: Create a payout instruction set
      description: >
        **Note:** The reference content in this section documents the Payments

        Engine endpoint. The Payments Engine endpoints include APIs available
        only

        for customers with Payments Engine enabled on their accounts.


        These endpoints are currently in beta and might be subject to

        changes.


        If you want to learn more about Fireblocks Payments Engine, please

        contact your Fireblocks Customer Success Manager or email

        CSM@fireblocks.com.


        **Create a payout instruction set.**


        A payout instruction set is a set of instructions for distributing
        payments

        from a single payment account to a list of payee accounts.


        The instruction set defines:


        - the payment account and its account type (vault, exchange, or fiat).

        - the account type (vault account, exchange account, whitelisted
        address,
          network connection, fiat account, or merchant account), the amount, and the
          asset of payment for each payee account.

        Learn more about Fireblocks Payments - Payouts in the following

        [guide](https://developers.fireblocks.com/docs/create-payouts).


        Endpoint Permission: Admin, Non-Signing Admin.
      operationId: createPayout
      parameters:
        - $ref: '#/components/parameters/X-Idempotency-Key'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePayoutRequest'
            example:
              paymentAccount:
                id: EX_SUB1
                type: EXCHANGE_ACCOUNT
              instructionSet:
                - payeeAccount:
                    id: bef85a1c-b605-4b2e-bdb5-2d400f4d0bf3
                    type: EXTERNAL_WALLET
                  amount:
                    amount: '43'
                    assetId: USDC
                - payeeAccount:
                    id: 3adc1f92-e791-44a8-9aee-7f31c2108b78
                    type: NETWORK_CONNECTION
                  amount:
                    amount: '4423'
                    assetId: USDC
      responses:
        '200':
          description: >-
            The payout instruction set creation succeeded and returns the
            generated instruction set with a unique payout IDThe payout ID will
            be used for executing the payout and checking the payout status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutResponse'
              example:
                payoutId: 1fe3b61f-7e1f-4a19-aff0-4f0a524d44d7
                paymentAccount:
                  id: EX_SUB2
                  type: EXCHANGE_ACCOUNT
                createdAt: 1645365800
                state: REQUESTED
                status: REGISTERED
                initMethod: API
                instructionSet:
                  - id: 6ea4a016-536b-49af-b1a0-40b343ccf879
                    name: payee-wallet-name
                    payeeAccount:
                      id: bef85a1c-b605-4b2e-bdb5-2d400f4d0bf3
                      type: EXTERNAL_WALLET
                    amount:
                      amount: '43'
                      assetId: USDC
                    state: NOT_STARTED
                    transactions: []
                  - id: e783a79b-6acc-4d18-885d-ed533cad8eeb
                    name: payee-by-network
                    payeeAccount:
                      id: 3adc1f92-e791-44a8-9aee-7f31c2108b78
                      type: NETWORK_CONNECTION
                    amount:
                      amount: '4423.23'
                      assetId: USDC
                    state: NOT_STARTED
                    transactions: []
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized. Missing / invalid JWT token in Authorization header.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        5XX:
          description: Internal error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-codeSamples:
        - lang: TypeScript
          source: >-
            const response: Promise<FireblocksResponse<PayoutResponse>> =
            fireblocks.paymentsPayout.createPayout(paymentsPayoutApiCreatePayoutRequest);
        - lang: Java
          source: >-
            CompletableFuture<ApiResponse<PayoutResponse>> response =
            fireblocks.paymentsPayout().createPayout(createPayoutRequest,
            idempotencyKey);
        - lang: Python
          source: >-
            response =
            fireblocks.payments_payout.create_payout(create_payout_request,
            idempotency_key);
components:
  parameters:
    X-Idempotency-Key:
      name: Idempotency-Key
      in: header
      description: >-
        A unique identifier for the request. If the request is sent multiple
        times with the same idempotency key, the server will return the same
        response as the first request. The idempotency key is valid for 24
        hours.
      required: false
      schema:
        type: string
  schemas:
    CreatePayoutRequest:
      type: object
      properties:
        paymentAccount:
          $ref: '#/components/schemas/PaymentAccount'
        instructionSet:
          type: array
          items:
            $ref: '#/components/schemas/PayoutInstruction'
      required:
        - paymentAccount
        - instructionSet
    PayoutResponse:
      type: object
      properties:
        payoutId:
          type: string
        paymentAccount:
          $ref: '#/components/schemas/PaymentAccountResponse'
        createdAt:
          type: number
        state:
          $ref: '#/components/schemas/PayoutState'
        status:
          $ref: '#/components/schemas/PayoutStatus'
        reasonOfFailure:
          type: string
          description: |
            - INSUFFICIENT_BALANCE
            - SOURCE_TRANSLATION
            - SOURCE_NOT_UNIQUE
            - SOURCE_NOT_FOUND
            - SOURCE_TYPE_NOT_SUPPORTED
            - EMPTY_SOURCE
            - DESTINATION_TRANSLATION
            - DESTINATION_NOT_UNIQUE
            - DESTINATION_NOT_FOUND
            - EMPTY_DESTINATION
            - PARSING
            - UNKNOWN
            - FIREBLOCKS_CLIENT
            - TRANSACTION_SUBMISSION
        initMethod:
          $ref: '#/components/schemas/PayoutInitMethod'
        instructionSet:
          type: array
          items:
            $ref: '#/components/schemas/PayoutInstructionResponse'
        reportUrl:
          type: string
      required:
        - payoutId
        - createdAt
        - state
        - status
        - paymentAccount
        - instructionSet
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum:
                - INTERNAL
                - AUTHENTICATION
                - AUTHORIZATION
                - VALIDATION
                - NOT_FOUND
                - UNPROCESSABLE_ENTITY
                - FORBIDDEN
            message:
              type: string
          required:
            - type
            - message
      required:
        - error
    PaymentAccount:
      type: object
      properties:
        id:
          type: string
        type:
          $ref: '#/components/schemas/PaymentAccountType'
      required:
        - id
        - type
    PayoutInstruction:
      type: object
      properties:
        id:
          type: string
        payeeAccount:
          $ref: '#/components/schemas/PayeeAccount'
        amount:
          $ref: '#/components/schemas/InstructionAmount'
      required:
        - amount
        - payeeAccount
    PaymentAccountResponse:
      type: object
      properties:
        id:
          type: string
        type:
          $ref: '#/components/schemas/PaymentAccountType'
    PayoutState:
      type: string
      enum:
        - CREATED
        - FILE_FOUND
        - REQUESTED
        - TRANSLATED
        - PROCESSING
        - SUBMITTED
        - FINALIZED
        - INSUFFICIENT_BALANCE
        - FAILED
      description: >
        - CREATED - payout instruction set created with all its details

        - FILE_FOUND - new file found in the FTP

        - REQUESTED - payout requested with all its details

        - TRANSLATED - payout instruction account IDs identified and translated

        - PROCESSING - payout instruction set executed and is processing

        - SUBMITTED - transactions submitted for payout instructions

        - FINALIZED - payout finished processing, all transactions processed
        successfully

        - INSUFFICIENT_BALANCE - insufficient balance in the payment account
        (can be a temporary state)

        - FAILED - one or more of the payout instructions failed
    PayoutStatus:
      type: string
      enum:
        - REGISTERED
        - VERIFYING
        - IN_PROGRESS
        - DONE
        - INSUFFICIENT_BALANCE
        - FAILED
      description: "- REQUESTED\tpayout requested with all its details\n- VERIFIED\tpayout instruction set details were verified\n- PROCESSING\tpayout instruction set executed and is processing\n- FINALIZED\tpayout done (all payout instructions completed successfully)\n- INSUFFICIENT_BALANCE\tinsufficient balance in the payment account (can be a temporary state)\n- FAILED\tone or more of the payout instructions failed\n"
    PayoutInitMethod:
      type: string
      enum:
        - FILE
        - API
    PayoutInstructionResponse:
      type: object
      properties:
        id:
          type: string
        payeeAccount:
          $ref: '#/components/schemas/PayeeAccountResponse'
        amount:
          $ref: '#/components/schemas/InstructionAmount'
        state:
          $ref: '#/components/schemas/PayoutInstructionState'
        transactions:
          type: array
          items:
            $ref: '#/components/schemas/Transaction'
      required:
        - amount
        - payeeAccount
        - state
        - transactions
    PaymentAccountType:
      type: string
      enum:
        - VAULT_ACCOUNT
        - EXCHANGE_ACCOUNT
        - FIAT_ACCOUNT
    PayeeAccount:
      type: object
      properties:
        id:
          type: string
        type:
          $ref: '#/components/schemas/PayeeAccountType'
      required:
        - id
        - type
    InstructionAmount:
      type: object
      properties:
        amount:
          type: string
        assetId:
          type: string
      required:
        - amount
        - assetId
    PayeeAccountResponse:
      type: object
      properties:
        id:
          type: string
        type:
          $ref: '#/components/schemas/PayeeAccountType'
    PayoutInstructionState:
      type: string
      enum:
        - NOT_STARTED
        - TRANSACTION_SENT
        - COMPLETED
        - FAILED
        - TRANSLATION_ERROR
        - SKIPPED
      description: "- NOT_STARTED\t- waiting to start\n- TRANSACTION_SENT - an underlying transaction was sent\n- COMPLETED\t- completed successfully\n- FAILED - failed\n- TRANSLATION_ERROR -lookup of the destination failed (due to changes in the underlying whitelisted external wallet or similar)\n- SKIPPED- no transaction(s) created for this instruction\n"
    Transaction:
      type: object
      properties:
        id:
          type: string
        state:
          type: string
          enum:
            - SUBMITTED
            - QUEUED
            - PENDING_AUTHORIZATION
            - PENDING_SIGNATURE
            - BROADCASTING
            - PENDING_3RD_PARTY_MANUAL_APPROVAL
            - PENDING_3RD_PARTY
            - PENDING
            - CONFIRMING
            - CONFIRMED
            - COMPLETED
            - PARTIALLY_COMPLETED
            - PENDING_AML_SCREENING
            - CANCELLING
            - CANCELLED
            - REJECTED
            - BLOCKED
            - FAILED
            - TIMEOUT
        timestamp:
          type: number
          format: date-time
        instructionId:
          type: string
      required:
        - id
        - state
    PayeeAccountType:
      type: string
      enum:
        - VAULT_ACCOUNT
        - EXCHANGE_ACCOUNT
        - INTERNAL_WALLET
        - EXTERNAL_WALLET
        - NETWORK_CONNECTION
        - FIAT_ACCOUNT
      description: "- VAULT_ACCOUNT  \ta native Fireblocks vault account\n- EXCHANGE_ACCOUNT \ta third-party exchange account\n- INTERNAL_WALLET \ta whitelisted address marked as internal to the workspace/organization\n- EXTERNAL_WALLET\ta whitelisted address marked as external\n- NETWORK_CONNECTION\ta member of the Fireblocks network\n- FIAT_ACCOUNT\ta third-party account of a fiat bank (Signature, BCB, etc)\n"

````