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

# Schedule Withdraw

## Overview

Schedule a USDC withdrawal request. This is step 1 of the two-phase withdrawal process.

Scheduling requires only a signature (no gas). The withdrawal will be processed and become claimable after system batching.

<Info>
  To avoid ambiguity, we denote the smallest possible multiple of USDC (0.000001 USDC) as one `uusdc`,
  which stands for µUSDC (micro-USDC), and denote the smallest possible multiple of a contract (0.01 contract)
  as one `ccontract` (centicontract).

  User-facing USDC balances are specified as fixed-point strings (e.g. `"1.2625"` for USDC). Contract quantities
  in the API and SDK are specified as integer `ccontracts` strings (e.g. `"1050"` for 10.50 contracts at precision 2).
</Info>

## Withdrawal Flow

Bison uses a two-phase withdrawal process:

1. **Schedule** (this endpoint): User signs a message to request a withdrawal for a specific amount
2. **Claim** (`/get-withdraw-authorization` + on-chain tx): User gets authorization and executes the withdrawal on-chain

## Request Body

<ParamField path="chain" type="string" required>
  Chain to withdraw on. One of `base` or `bsc`.
</ParamField>

<ParamField path="userAddress" type="string" required>
  User's Ethereum wallet address.
</ParamField>

<ParamField path="amountUusdc" type="string" required>
  Amount to withdraw in µUSDC as an integer string. Must be positive and not exceed deposited balance.
</ParamField>

<ParamField path="signature" type="string" required>
  EIP-712 signature from the user authorizing the withdrawal request.
</ParamField>

<ParamField path="expiry" type="number" required>
  Unix timestamp when the signature expires. Should be set to \~10 minutes in the future.
</ParamField>

## Response

<ResponseField name="withdrawId" type="string">
  Unique identifier for the scheduled withdrawal.
</ResponseField>

<ResponseField name="amountUusdc" type="string">
  Amount scheduled for withdrawal in µUSDC (integer string).
</ResponseField>

<ResponseField name="status" type="string">
  Initial withdrawal status. One of `pending`, `fill-locked`, `unclaimed`, or `claimed`.
</ResponseField>

<ResponseField name="scheduledAt" type="string">
  ISO 8601 timestamp when the withdrawal was scheduled.
</ResponseField>

## Withdrawal Status Flow

Withdrawals progress through these statuses:

1. **pending**: Scheduled, waiting for system processing
2. **fill-locked**: Being processed by the system
3. **unclaimed**: Ready to claim on-chain
4. **claimed**: Successfully withdrawn

## Error Responses

<ResponseField name="400 - Insufficient Balance">
  Returned when the withdrawal amount exceeds available balance.

  ```json theme={null}
  {
    "error": "Insufficient balance for withdrawal"
  }
  ```
</ResponseField>

<ResponseField name="400 - Invalid Signature">
  Returned when the signature is invalid or expired.

  ```json theme={null}
  {
    "error": "Invalid signature"
  }
  ```
</ResponseField>

<ResponseField name="500 - Server Error">
  Returned when scheduling fails.

  ```json theme={null}
  {
    "error": "Failed to schedule withdrawal"
  }
  ```
</ResponseField>

## EIP-712 Signature

The signature must be generated using EIP-712 typed data with the following structure:

```typescript theme={null}
const domain = {
  name: 'BisonScheduleWithdraw',
  version: '1',
  chainId: 8453, // Base mainnet
};

const types = {
  ScheduleWithdraw: [
    { name: 'userAddress', type: 'address' },
    { name: 'amountUusdc', type: 'uint256' },
    { name: 'expiry', type: 'uint256' },
  ],
};

const message = {
  userAddress: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266',
  amountUusdc: BigInt(50_000_000), // 50 USDC
  expiry: BigInt(Math.floor(Date.now() / 1000) + 600), // 10 minutes
};
```

## Example Request

```json theme={null}
{
  "chain": "base",
  "userAddress": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
  "amountUusdc": 50000000,
  "signature": "0x1234567890abcdef...",
  "expiry": 1699565430
}
```

## Example Response

```json theme={null}
{
  "withdrawId": "550e8400-e29b-41d4-a716-446655440000",
  "amountUusdc": 50000000,
  "status": "pending",
  "scheduledAt": "2024-11-09T15:30:00.000Z"
}
```

## Important Notes

* No gas is required to schedule a withdrawal
* Withdrawal amount is deducted from deposited balance immediately
* Multiple withdrawals can be scheduled and will be batched when claiming
* Signature expires after the specified `expiry` timestamp
* Use `/pending-withdraws/{userAddress}` to check withdrawal status


## OpenAPI

````yaml POST /schedule-withdraw
openapi: 3.0.0
info:
  version: 1.0.0
  title: Bison API
servers: []
security: []
paths:
  /schedule-withdraw:
    post:
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                userAddress:
                  type: string
                chain:
                  type: string
                  enum:
                    - base
                    - bsc
                amountUusdc:
                  type: string
                  description: >-
                    Amount to withdraw in µUSDC (micro-USDC, 1 µUSDC = 0.000001
                    USD). Must be positive integer string.
                  example: '1000000'
                signature:
                  type: string
                expiry:
                  type: number
              required:
                - userAddress
                - chain
                - amountUusdc
                - signature
                - expiry
      responses:
        '200':
          description: Withdraw scheduled successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  withdrawId:
                    type: string
                  amountUusdc:
                    type: string
                  status:
                    type: string
                    enum:
                      - pending
                      - fill-locked
                      - unclaimed
                      - claimed
                  scheduledAt:
                    type: string
                required:
                  - withdrawId
                  - amountUusdc
                  - status
                  - scheduledAt
        '400':
          description: Invalid request or insufficient balance
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error

````