Skip to main content
POST
/
schedule-withdraw
cURL
curl --request POST \
  --url https://api.example.com/schedule-withdraw \
  --header 'Content-Type: application/json' \
  --data '
{
  "userAddress": "<string>",
  "chain": "base",
  "amountUusdc": 1,
  "signature": "<string>",
  "expiry": 123
}
'
{
  "withdrawId": "<string>",
  "amountUusdc": 123,
  "status": "pending",
  "scheduledAt": "<string>"
}

​
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.
To avoid ambiguity, we denote the smallest possible multiple of USDC (0.000001 USDC) as one uusdc, which stands for µUSDC (micro-USDC).

​
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

​
chain
string
required
Chain to withdraw on. One of base or bsc.
​
userAddress
string
required
User’s Ethereum wallet address.
​
amountUusdc
number
required
Amount to withdraw in µUSDC. Must be positive and not exceed deposited balance.
​
signature
string
required
EIP-712 signature from the user authorizing the withdrawal request.
​
expiry
number
required
Unix timestamp when the signature expires. Should be set to ~10 minutes in the future.

​
Response

​
withdrawId
string
Unique identifier for the scheduled withdrawal.
​
amountUusdc
number
Amount scheduled for withdrawal in µUSDC.
​
status
string
Initial withdrawal status. One of pending, fill-locked, unclaimed, or claimed.
​
scheduledAt
string
ISO 8601 timestamp when the withdrawal was scheduled.

​
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

​
400 - Insufficient Balance
Returned when the withdrawal amount exceeds available balance.
{
  "error": "Insufficient balance for withdrawal"
}
​
400 - Invalid Signature
Returned when the signature is invalid or expired.
{
  "error": "Invalid signature"
}
​
500 - Server Error
Returned when scheduling fails.
{
  "error": "Failed to schedule withdrawal"
}

​
EIP-712 Signature

The signature must be generated using EIP-712 typed data with the following structure: 
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

{
  "chain": "base",
  "userAddress": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
  "amountUusdc": 50000000,
  "signature": "0x1234567890abcdef...",
  "expiry": 1699565430
}

​
Example Response

{
  "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

Body

application/json
​
userAddress
string
required
​
chain
enum<string>
required
Available options:
base,
bsc
​
amountUusdc
number
required
Required range: x > 0
​
signature
string
required
​
expiry
number
required

Response

Withdraw scheduled successfully

​
withdrawId
string
required
​
amountUusdc
number
required
​
status
enum<string>
required
Available options:
pending,
fill-locked,
unclaimed,
claimed
​
scheduledAt
string
required