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

# Create a payout

> 
Create a stablecoin payout.

The following table includes the supported pairs of `amount.currency` and `toAmount.currency` for stablecoin address book payouts:

| amount.currency  | toAmount.currency |
| ---------------- | ----------------- |
| USD              | USD               |
| EUR              | EUR               |

Required fields depend on your Circle entity; use the request body options that match your integration.

For Singapore (CIRCLE_SG) entities, `purposeOfTransfer` is **required** and must use a payment reason code from [Crypto Payouts payment reason codes](https://developers.circle.com/circle-mint/crypto-payouts-payment-reason-codes). Invalid or missing values can return error code `5020`.




## OpenAPI

````yaml openapi/payouts.yaml post /v1/payouts
openapi: 3.0.2
info:
  version: ${version}
  title: Crypto Payouts API
  description: >-
    The Circle Payouts API allows you to programmatically make fast, global
    payouts to your customers, vendors, and suppliers. Make payouts on supported
    blockchains.
servers:
  - url: https://api-sandbox.circle.com
  - url: https://api.circle.com
security: []
tags:
  - name: Payouts
    description: Create and get information on address book payouts.
  - name: Crypto Address Book
    description: Manage blockchain addresses with metadata.
paths:
  /v1/payouts:
    post:
      tags:
        - Payouts
      summary: Create a payout
      description: >

        Create a stablecoin payout.


        The following table includes the supported pairs of `amount.currency`
        and `toAmount.currency` for stablecoin address book payouts:


        | amount.currency  | toAmount.currency |

        | ---------------- | ----------------- |

        | USD              | USD               |

        | EUR              | EUR               |


        Required fields depend on your Circle entity; use the request body
        options that match your integration.


        For Singapore (CIRCLE_SG) entities, `purposeOfTransfer` is **required**
        and must use a payment reason code from [Crypto Payouts payment reason
        codes](https://developers.circle.com/circle-mint/crypto-payouts-payment-reason-codes).
        Invalid or missing values can return error code `5020`.
      operationId: createPayout
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - title: General customers
                  description: For Circle entities other than CIRCLE_SG.
                  allOf:
                    - $ref: '#/components/schemas/CryptoPayoutCreationRequest'
                - title: SG customers
                  description: >-
                    For Singapore (CIRCLE_SG) entities. `purposeOfTransfer` is
                    required.
                  allOf:
                    - $ref: '#/components/schemas/CryptoPayoutCreationRequest'
                    - type: object
                      required:
                        - purposeOfTransfer
                      properties:
                        purposeOfTransfer:
                          $ref: '#/components/schemas/CryptoPayoutPurposeOfTransfer'
      responses:
        '201':
          description: Successfully created a payout.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                title: CreatePayoutResponse
                properties:
                  data:
                    $ref: '#/components/schemas/CryptoPayoutResponseData'
              examples:
                Crypto Payout:
                  value:
                    data:
                      id: b8627ae8-732b-4d25-b947-1df8f4007a29
                      sourceWalletId: '53535335'
                      destination:
                        type: address_book
                        id: b8627ae8-732b-4d25-b947-1df8f4007a29
                      amount:
                        amount: '3.14'
                        currency: USD
                      toAmount:
                        amount: '3.14'
                        currency: ETH
                      fees:
                        amount: '3.14'
                        currency: USD
                      networkFees:
                        amount: '0.14'
                        currency: USD
                      purposeOfTransfer: PMT001
                      status: pending
                      errorCode: transaction_denied
                      riskEvaluation:
                        decision: denied
                        reason: '4000'
                      createDate: '2020-04-10T02:13:30.000Z'
                      updateDate: '2020-04-10T02:13:30.000Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/NotAuthorized'
      security:
        - bearerAuth: []
components:
  schemas:
    CryptoPayoutCreationRequest:
      type: object
      required:
        - idempotencyKey
        - destination
        - amount
      properties:
        idempotencyKey:
          $ref: '#/components/schemas/IdempotencyKey'
        source:
          $ref: '#/components/schemas/TransferSourceWalletLocation'
        destination:
          $ref: '#/components/schemas/CryptoPayoutDestination'
        amount:
          $ref: '#/components/schemas/CryptoPayoutMoney'
        toAmount:
          $ref: '#/components/schemas/CryptoPayoutMoney'
        purposeOfTransfer:
          $ref: '#/components/schemas/CryptoPayoutPurposeOfTransfer'
    CryptoPayoutPurposeOfTransfer:
      type: string
      description: >
        Payment reason code for the payout. Aligned with Circle payment reason
        codes for Crypto Payouts. Do not use `PMT006`. See [Crypto Payouts
        payment reason
        codes](https://developers.circle.com/circle-mint/crypto-payouts-payment-reason-codes).


        Invalid values can return error code `5020`.
      enum:
        - PMT000
        - PMT001
        - PMT002
        - PMT003
        - PMT004
        - PMT005
        - PMT007
        - PMT008
        - PMT009
        - PMT010
        - PMT011
        - PMT012
        - PMT013
        - PMT014
        - PMT015
        - PMT016
        - PMT017
        - PMT018
        - PMT019
        - PMT020
        - PMT021
        - PMT022
        - PMT023
        - PMT024
        - PMT025
        - PMT026
        - PMT027
        - PMT028
        - PMT029
        - PMT030
      example: PMT001
    CryptoPayoutResponseData:
      description: >
        Payout resource returned by create and get operations. Includes
        `purposeOfTransfer` when it was provided at create time (required for
        CIRCLE_SG entities).
      allOf:
        - $ref: '#/components/schemas/CryptoPayoutResponseGeneral'
        - type: object
          properties:
            purposeOfTransfer:
              $ref: '#/components/schemas/CryptoPayoutPurposeOfTransfer'
    IdempotencyKey:
      type: string
      description: >-
        Universally unique identifier (UUID v4) idempotency key. This key is
        utilized to ensure exactly-once execution of mutating requests.
      format: uuid
      example: ba943ff1-ca16-49b2-ba55-1057e70ca5c7
    TransferSourceWalletLocation:
      description: A source wallet location.
      type: object
      required:
        - type
        - id
      properties:
        type:
          type: string
          enum:
            - wallet
        id:
          type: string
          description: The id of the wallet.
          example: '12345'
        identities:
          type: array
          items:
            $ref: '#/components/schemas/Identity'
        useMainWalletFunding:
          type: boolean
          description: >
            When true, if the designated source wallet lacks sufficient funds
            for the payout, funds are transferred from the master wallet to the
            source wallet before the payout executes.

            For Managed Payments customers only. Default is true.
    CryptoPayoutDestination:
      type: object
      description: The destination.
      required:
        - type
        - id
      properties:
        type:
          $ref: '#/components/schemas/CryptoPayoutDestinationType'
        id:
          $ref: '#/components/schemas/Id'
    CryptoPayoutMoney:
      type: object
      required:
        - amount
        - currency
      properties:
        amount:
          type: string
          description: >
            The numeric value of the amount, expressed in units of the specified
            currency.

            Use a period (`.`) as the decimal separator.
          example: '3.14'
        currency:
          type: string
          description: The ISO 4217 currency code for the amount.
          enum:
            - USD
            - EUR
    CryptoPayoutResponseGeneral:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/Id'
        sourceWalletId:
          type: string
          description: The identifier of the source wallet used to fund a payout.
          example: '53535335'
        destination:
          $ref: '#/components/schemas/CryptoPayoutDestination'
        amount:
          $ref: '#/components/schemas/PayoutMoney'
        toAmount:
          $ref: '#/components/schemas/PayoutMoney'
        fees:
          $ref: '#/components/schemas/PayoutMoney'
        networkFees:
          $ref: '#/components/schemas/PayoutMoney'
        status:
          $ref: '#/components/schemas/PayoutStatus'
        errorCode:
          $ref: '#/components/schemas/PayoutErrorCode'
        riskEvaluation:
          $ref: '#/components/schemas/RiskEvaluation'
        createDate:
          $ref: '#/components/schemas/UtcTimestamp'
        updateDate:
          $ref: '#/components/schemas/UtcTimestamp'
    Identity:
      type: object
      description: |
        The identity of the originator. Identities are required when:
          * `destination.type: "blockchain"`
          * `destination.chain: "ETH"`
          * `amount.amount` >= $3,000 in value
      required:
        - type
        - name
        - addresses
      properties:
        type:
          type: string
          description: >
            The type of identity for the originator.

            * `individual` - A uniquely distinguishable individual.

            * `business` - Any entity other than a natural person that can
            establish a permanent customer relationship with an affected entity
            or otherwise own property. This can include companies, foundations,
            anstalt, partnerships, associations and other relevantly similar
            entities.
          enum:
            - individual
            - business
        name:
          type: string
          description: Full name of the identity.
          example: Satoshi Nakamoto
          maxLength: 1024
        addresses:
          type: array
          items:
            $ref: '#/components/schemas/IdentityAddress'
    CryptoPayoutDestinationType:
      type: string
      description: The destination type.
      enum:
        - address_book
    Id:
      type: string
      description: Unique system generated identifier for the entity.
      format: uuid
      example: b8627ae8-732b-4d25-b947-1df8f4007a29
    PayoutMoney:
      type: object
      required:
        - amount
        - currency
      properties:
        amount:
          type: string
          description: Magnitude of the amount, in units of the currency, with a `.`.
          example: '3.14'
        currency:
          type: string
          description: Currency code for the amount.
          enum:
            - USD
            - EUR
            - BTC
            - ETH
            - MTC
            - FLW
            - MAN
    PayoutStatus:
      type: string
      description: >-
        Status of the payout. Status `pending` indicates that the payout is in
        process; `complete` indicates it finished successfully; `failed`
        indicates it failed.
      enum:
        - pending
        - complete
        - failed
    PayoutErrorCode:
      type: string
      nullable: true
      description: >-
        Indicates the failure reason of a payout. Only present for payouts in
        failed state. Possible values are [`insufficient_funds`,
        `transaction_denied`, `transaction_failed`, `transaction_returned`,
        `bank_transaction_error`, `fiat_account_limit_exceeded`,
        `invalid_bank_account_number`, `invalid_ach_rtn`, `invalid_wire_rtn`,
        `vendor_inactive`]'
      enum:
        - insufficient_funds
        - transaction_denied
        - transaction_failed
        - transaction_returned
        - bank_transaction_error
        - fiat_account_limit_exceeded
        - invalid_bank_account_number
        - invalid_ach_rtn
        - invalid_wire_rtn
        - vendor_inactive
    RiskEvaluation:
      type: object
      description: >-
        Results of risk evaluation. Only present if the payment is denied by
        Circle's risk service.
      nullable: true
      properties:
        decision:
          description: Enumerated decision of the account.
          type: string
          enum:
            - approved
            - denied
            - review
        reason:
          description: Risk reason for the definitive decision outcome.
          type: string
          nullable: true
          example: '3000'
    UtcTimestamp:
      type: string
      description: ISO-8601 UTC date/time format.
      example: '2020-04-10T02:13:30.000Z'
    IdentityAddress:
      type: object
      required:
        - line1
        - city
        - district
        - postalCode
        - country
      properties:
        line1:
          type: string
          description: Line one of the street address.
          maxLength: 1024
          example: 100 Money Street
        line2:
          type: string
          description: Line two of the street address.
          maxLength: 1024
          example: Suite 1
        city:
          type: string
          description: City portion of the address.
          maxLength: 1024
          example: Boston
        district:
          description: >-
            State / County / Province / Region portion of the address. If the
            country is US or Canada, then district is required and should use
            the two-letter code for the subdivision.
          type: string
          maxLength: 16
          example: MA
        postalCode:
          type: string
          description: Postal / ZIP code of the address.
          maxLength: 16
          example: '01234'
        country:
          type: string
          description: >-
            Country portion of the address. Formatted as a two-letter country
            code specified in ISO 3166-1 alpha-2.
          maxLength: 2
          example: US
  headers:
    XRequestId:
      description: >-
        Universally unique identifier (UUID v4) for the request. Helpful for
        identifying a request when communicating with Circle support.
      schema:
        type: string
        format: uuid
        example: 2adba88e-9d63-44bc-b975-9b6ae3440dde
  responses:
    BadRequest:
      description: The request cannot be processed due to a client error.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
      content:
        application/json:
          schema:
            type: object
            title: BadRequest
            required:
              - code
              - message
            properties:
              code:
                type: integer
                example: 400
              message:
                type: string
                example: Something went wrong.
            example:
              code: 400
              message: Bad request.
          examples:
            response:
              value:
                code: 400
                message: Bad request.
    NotAuthorized:
      description: >-
        The request has not been applied because it lacks valid authentication
        credentials.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
      content:
        application/json:
          schema:
            type: object
            title: NotAuthorized
            required:
              - code
              - message
            properties:
              code:
                type: integer
                example: 400
              message:
                type: string
                example: Something went wrong.
            example:
              code: 401
              message: Malformed authorization.
          examples:
            response:
              value:
                code: 401
                message: Malformed authorization.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````