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

# Request a withdrawal signature payload

> Creates a ChangeNOW relay route from fixed source collateral (USDC on Base in production, rUSD on Base Sepolia in sandbox) to the selected destination and returns Rain withdrawal signature parameters for onchain execution.



## OpenAPI

````yaml openapi.yaml post /partner/v1/withdrawals
openapi: 3.1.0
info:
  title: Machines Cash API
  version: 0.3.0
  description: >
    API for KYC, cards, encryption, balances, deposits, transactions, and
    withdrawals.

    All responses use a consistent envelope by default: { ok, data, summary,
    errors[], next }.

    Set X-Open-Responses: 1 to receive Open Responses-style response objects.
servers:
  - url: https://api.machines.cash
    description: production
  - url: https://dev-api.machines.cash
    description: sandbox
security: []
tags:
  - name: users
  - name: sessions
  - name: kyc
  - name: kycValues
  - name: agreements
  - name: cards
  - name: encryption
  - name: balances
  - name: deposits
  - name: transactions
  - name: withdrawals
paths:
  /partner/v1/withdrawals:
    parameters:
      - $ref: '#/components/parameters/OpenResponses'
      - $ref: '#/components/parameters/OpenResponsesCallId'
    post:
      tags:
        - withdrawals
      summary: Request a withdrawal signature payload
      description: >-
        Creates a ChangeNOW relay route from fixed source collateral (USDC on
        Base in production, rUSD on Base Sepolia in sandbox) to the selected
        destination and returns Rain withdrawal signature parameters for onchain
        execution.
      operationId: api.withdrawals.create
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WithdrawalRequest'
      responses:
        '200':
          description: Withdrawal signature payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WithdrawalResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      security:
        - Session: []
components:
  parameters:
    OpenResponses:
      name: X-Open-Responses
      in: header
      required: false
      schema:
        type: string
        enum:
          - '1'
          - 'true'
      description: >-
        Return Open Responses-compatible output when set (replaces the default
        response envelope).
    OpenResponsesCallId:
      name: X-Open-Responses-Call-Id
      in: header
      required: false
      schema:
        type: string
        minLength: 1
      description: >-
        Tool call id used for function_call_output items when Open Responses
        mode is enabled.
  schemas:
    WithdrawalRequest:
      type: object
      additionalProperties: false
      required:
        - amountCents
        - destination
      properties:
        amountCents:
          type: integer
          minimum: 1
          description: Amount in cents.
        source:
          $ref: '#/components/schemas/WithdrawalSource'
        destination:
          $ref: '#/components/schemas/WithdrawalDestination'
        adminAddress:
          $ref: '#/components/schemas/WalletAddress'
          description: >-
            Recommended. Admin EOA that will sign and broadcast the onchain
            `withdrawAsset` transaction.
    WithdrawalResponse:
      type: object
      additionalProperties: false
      required:
        - ok
        - data
        - summary
        - errors
      properties:
        ok:
          type: boolean
          const: true
        data:
          $ref: '#/components/schemas/WithdrawalPayload'
        summary:
          type: string
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorDetail'
        next:
          $ref: '#/components/schemas/NextHint'
    WithdrawalSource:
      type: object
      additionalProperties: false
      properties:
        chainId:
          type: integer
          minimum: 1
          description: >-
            Optional source chain hint. Defaults to Base (8453) in production
            and Base Sepolia in sandbox.
        tokenAddress:
          $ref: '#/components/schemas/TokenAddress'
          description: >-
            Optional source token hint. Defaults to USDC collateral token in
            production and rUSD token in sandbox.
        contractId:
          type:
            - string
            - 'null'
          format: uuid
          description: >-
            Optional Rain collateral contract id override. No
            `/partner/v1/contracts` endpoint exists; omit this field unless you
            already know the id.
    WithdrawalDestination:
      type: object
      additionalProperties: false
      required:
        - currency
        - network
        - address
      properties:
        currency:
          type: string
          example: hbar
        network:
          type: string
          example: hbar
        address:
          type: string
          minLength: 1
          maxLength: 200
          description: Destination payout address for ChangeNOW.
        extraId:
          type:
            - string
            - 'null'
          description: Optional destination memo/tag for payout networks that require it.
    WalletAddress:
      type: string
      pattern: ^0x[a-fA-F0-9]{40}$
      example: '0x2b0f7f2f7c8e4c3d2d3b3f6a8f9b0c1d2e3f4a5b'
    WithdrawalPayload:
      type: object
      additionalProperties: false
      required:
        - status
      properties:
        status:
          type: string
          enum:
            - pending
            - ready
        retryAfterSeconds:
          type:
            - integer
            - 'null'
        parameters:
          type:
            - array
            - 'null'
          minItems: 7
          maxItems: 7
          description: >-
            Ordered withdrawal args `[collateralProxy, token, amount, recipient,
            expiresAt, executorSalt, executorSignature]`.
          items:
            type: string
        execution:
          anyOf:
            - $ref: '#/components/schemas/WithdrawalExecution'
            - type: 'null'
        relay:
          anyOf:
            - $ref: '#/components/schemas/WithdrawalRelay'
            - type: 'null'
        signature:
          anyOf:
            - $ref: '#/components/schemas/WithdrawalSignature'
            - type: 'null'
        expiresAt:
          type:
            - string
            - 'null'
          format: date-time
    ErrorDetail:
      type: object
      additionalProperties: false
      required:
        - code
        - message
      properties:
        code:
          type: string
          example: invalid_request
        message:
          type: string
          example: missing required field
        field:
          type: string
          description: Optional field name that caused the error.
    NextHint:
      type: object
      additionalProperties: false
      properties:
        pollAfterMs:
          type: integer
          minimum: 0
        suggestedTool:
          type: string
        suggestedArgs:
          type: object
          additionalProperties: true
    ErrorResponse:
      type: object
      additionalProperties: false
      required:
        - ok
        - summary
        - errors
      properties:
        ok:
          type: boolean
          const: false
        summary:
          type: string
          example: invalid request
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorDetail'
        next:
          $ref: '#/components/schemas/NextHint'
    TokenAddress:
      type: string
      pattern: ^0x[a-fA-F0-9]{40}$
      example: '0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174'
    WithdrawalExecution:
      type: object
      additionalProperties: false
      required:
        - contractId
        - contractVersion
        - chainId
        - collateralProxyAddress
        - controllerAddress
        - coordinatorAddress
        - callTarget
        - callPath
      properties:
        contractId:
          type:
            - string
            - 'null'
        contractVersion:
          type:
            - integer
            - 'null'
          description: >-
            Collateral contract version (v1 uses controller path, v2 uses
            coordinator path).
        chainId:
          type:
            - integer
            - 'null'
          description: EVM chain id where the withdrawal tx must be sent.
        collateralProxyAddress:
          type:
            - string
            - 'null'
          description: Collateral proxy address (also first item in `parameters`).
        controllerAddress:
          type:
            - string
            - 'null'
        coordinatorAddress:
          type:
            - string
            - 'null'
        callTarget:
          type:
            - string
            - 'null'
          description: >-
            Contract address to use as tx `to` (controller for v1 or coordinator
            for v2).
        callPath:
          type: string
          enum:
            - controller_v1
            - coordinator_v2
            - unknown
          description: >
            - `controller_v1`: call 7-arg `withdrawAsset(...)`

            - `coordinator_v2`: call 10-arg `withdrawAsset(...)` with admin
            typed-data signature values

            - `unknown`: cannot infer call path from available contract metadata
    WithdrawalRelay:
      type: object
      additionalProperties: false
      required:
        - changeNowId
        - payinAddress
        - payinExtraId
        - payoutAddress
        - payoutExtraId
        - fromCurrency
        - fromNetwork
        - toCurrency
        - toNetwork
      properties:
        changeNowId:
          type: string
        payinAddress:
          type: string
        payinExtraId:
          type:
            - string
            - 'null'
        payoutAddress:
          type: string
        payoutExtraId:
          type:
            - string
            - 'null'
        fromCurrency:
          type: string
        fromNetwork:
          type: string
        toCurrency:
          type: string
        toNetwork:
          type: string
    WithdrawalSignature:
      type: object
      additionalProperties: false
      properties:
        data:
          type:
            - string
            - 'null'
        salt:
          type:
            - string
            - 'null'
        parameters:
          type: array
          minItems: 7
          maxItems: 7
          description: Same ordered args as `data.parameters`.
          items:
            type: string
  responses:
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    Session:
      type: http
      scheme: bearer
      bearerFormat: JWT

````