Developer Fees - Bison API

Overview

The SDK provides methods for developers to manage their accounts, check fee balances, and claim fees:

getDevAccountInfo - Get your dev account configuration and settings
getDevAccountFees - Check fee balances for your dev account
getDevFeeClaimHistory - View history of completed fee claims
getFeeClaimAuthorization - Get an authorization signature to claim fees
claimDevFees - High-level method that handles authorization and transaction submission

To avoid ambiguity, we denote the smallest possible multiple of USDC (0.000001 USDC) as one uusdc, which stands for µUSDC (micro-USDC).

Configuration

Developer fee methods require configuring devFlags when creating the client. This enables EIP-712 signature-based authentication with the API.

import { createBisonClient } from '@bison-markets/sdk-ts';

const client = createBisonClient({ 
  baseUrl: 'https://api.bison.markets',
  devFlags: {
    privateKey: '0x...',  // Your dev account signer's private key
    devAccountId: 'my-dev-account',
  },
});

Never expose your private key in client-side code. These methods are intended for server-side or CLI usage where the private key can be securely managed.

Getting Account Info

Retrieve your dev account configuration and settings.

`getDevAccountInfo`

async getDevAccountInfo(): Promise<{
  id: string;
  name: string;
  email: string;
  grossFeeBps: number;
  grossBaseFeeUusdc: number;
  bisonFeeCutBps: number;
  payoutChain: string;
  signerAddress: string;
  createdAt: string;
}>

Returns

string

Dev account identifier

name

string

Dev account display name

string

Dev account email

grossFeeBps

number

Your fee rate in basis points (100 = 1%)

grossBaseFeeUusdc

number

Flat fee per trade in µUSDC

bisonFeeCutBps

number

Bison’s share of your gross fees in basis points

payoutChain

string

Chain where fees can be claimed

signerAddress

string

Address that will receive fee payouts

createdAt

string

Account creation timestamp (ISO 8601)

Example

const info = await client.getDevAccountInfo();

console.log('Dev Account:', info.name);
console.log(`  Fee Rate: ${info.grossFeeBps / 100}%`);
console.log(`  Base Fee: ${info.grossBaseFeeUusdc / 1_000_000} USDC per trade`);
console.log(`  Bison Cut: ${info.bisonFeeCutBps / 100}% of gross fees`);
console.log(`  Payout Chain: ${info.payoutChain}`);
console.log(`  Signer: ${info.signerAddress}`);
// Expected output:
// Dev Account: My Trading App
//   Fee Rate: 0.5%
//   Base Fee: 0.10 USDC per trade
//   Bison Cut: 20% of gross fees
//   Payout Chain: base
//   Signer: 0xf39F...2266

Checking Fee Balances

Query your dev account’s accumulated fees across different states.

`getDevAccountFees`

async getDevAccountFees(): Promise<{
  id: string;
  name: string;
  pendingFeesUusdc: number;
  lockedFeesUusdc: number;
  unclaimedFeesUusdc: number;
  payoutChain: string;
  signerAddress: string;
}>

This method automatically uses your configured devFlags for authentication.

Returns

string

Dev account identifier

name

string

Dev account display name

pendingFeesUusdc

number

Fees from trades that haven’t been confirmed yet

lockedFeesUusdc

number

Fees locked for payout (awaiting operator settlement)

unclaimedFeesUusdc

number

Fees available to claim via the vault contract

payoutChain

string

Chain where fees can be claimed

signerAddress

string

Address that will receive fee payouts

Example

import { createBisonClient } from '@bison-markets/sdk-ts';

const client = createBisonClient({ 
  baseUrl: 'https://api.bison.markets',
  devFlags: {
    privateKey: process.env.DEV_PRIVATE_KEY as `0x${string}`,
    devAccountId: 'my-dev-account',
  },
});

const fees = await client.getDevAccountFees();

console.log('Fee balances:');
console.log(`  Pending: ${fees.pendingFeesUusdc / 1_000_000} USDC`);
console.log(`  Locked: ${fees.lockedFeesUusdc / 1_000_000} USDC`);
console.log(`  Claimable: ${fees.unclaimedFeesUusdc / 1_000_000} USDC`);
console.log(`  Payout chain: ${fees.payoutChain}`);
// Expected output:
// Fee balances:
//   Pending: 12.50 USDC
//   Locked: 0 USDC
//   Claimable: 45.00 USDC
//   Payout chain: base

Fee Claim History

View your past fee claim withdrawals.

`getDevFeeClaimHistory`

async getDevFeeClaimHistory(params?: {
  limit?: number;
  cursor?: string;
}): Promise<{
  claims: Array<{
    id: string;
    chain: string;
    amountUusdc: number;
    payoutAddress: string;
    claimedAt: string;
  }>;
  pagination: {
    total: number;
    hasMore: boolean;
    nextCursor?: string;
  };
}>

Parameters

limit

number

Maximum number of claims to return (default: 50, max: 200)

cursor

string

Pagination cursor from a previous response

Returns

claims

array

Array of fee claim records, sorted by most recent first

claims[].id

string

Unique identifier for the claim

claims[].chain

string

Chain where the claim was processed

claims[].amountUusdc

number

Amount claimed in µUSDC

claims[].payoutAddress

string

Address that received the payout

claims[].claimedAt

string

Timestamp when the claim was completed (ISO 8601)

pagination.total

number

Number of claims returned in this response

pagination.hasMore

boolean

Whether more claims are available

pagination.nextCursor

string

Cursor to fetch the next page (only present if hasMore is true)

Example

const { claims, pagination } = await client.getDevFeeClaimHistory({ limit: 10 });

console.log('Recent fee claims:');
for (const claim of claims) {
  const amount = claim.amountUusdc / 1_000_000;
  const date = new Date(claim.claimedAt).toLocaleDateString();
  console.log(`  ${date}: $${amount.toFixed(2)} on ${claim.chain}`);
}
// Expected output:
// Recent fee claims:
//   12/15/2025: $125.50 on base
//   12/10/2025: $89.25 on base

if (pagination.hasMore) {
  // Fetch more claims
  const nextPage = await client.getDevFeeClaimHistory({ 
    limit: 10, 
    cursor: pagination.nextCursor 
  });
}

Claiming Fees

Claim accumulated fees from the vault contract to your signer address.

`claimDevFees`

This high-level method handles getting the authorization signature and submitting the claim transaction.

async claimDevFees(params: {
  walletClient: WalletClient;
  publicClient: PublicClient;
}): Promise<`0x${string}`>

Parameters

walletClient

WalletClient

required

Viem wallet client for signing transactions

publicClient

PublicClient

required

Viem public client for reading contract state

Returns

Transaction hash of the fee claim transaction.

Example

import { createBisonClient } from '@bison-markets/sdk-ts';
import { createWalletClient, createPublicClient, http, custom } from 'viem';
import { base } from 'viem/chains';

const client = createBisonClient({ 
  baseUrl: 'https://api.bison.markets',
  devFlags: {
    privateKey: process.env.DEV_PRIVATE_KEY as `0x${string}`,
    devAccountId: 'my-dev-account',
  },
});

const walletClient = createWalletClient({
  chain: base,
  transport: custom(window.ethereum!),
});

const publicClient = createPublicClient({
  chain: base,
  transport: http(),
});

// Check claimable balance first
const fees = await client.getDevAccountFees();

if (fees.unclaimedFeesUusdc > 0) {
  console.log(`Claiming ${fees.unclaimedFeesUusdc / 1_000_000} USDC...`);
  
  const txHash = await client.claimDevFees({
    walletClient,
    publicClient,
  });
  
  console.log('Fees claimed! Transaction:', txHash);
  // Expected output: "Fees claimed! Transaction: 0xabc123..."
} else {
  console.log('No fees available to claim');
}

Low-Level Authorization

For advanced use cases, you can get the authorization signature directly.

`getFeeClaimAuthorization`

async getFeeClaimAuthorization(): Promise<{
  uuid: string;
  signature: string;
  expiresAt: number;
  amount: number;
  chain: string;
  signerAddress: string;
}>

The authorization expires after 30 seconds. If you don’t use it in time, you’ll need to request a new one.

Example

import { VAULT_ABI } from '@bison-markets/sdk-ts';

const auth = await client.getFeeClaimAuthorization();

console.log('Fee claim authorization:');
console.log(`  Amount: ${auth.amount / 1_000_000} USDC`);
console.log(`  Chain: ${auth.chain}`);
console.log(`  Expires at: ${new Date(auth.expiresAt * 1000).toISOString()}`);

// Use the authorization with the vault contract
const chainInfo = await client.getInfo();
const vaultAddress = chainInfo.chains[auth.chain].vaultAddress;

const txHash = await walletClient.writeContract({
  address: vaultAddress,
  abi: VAULT_ABI,
  functionName: 'withdrawUSDC',
  args: [
    auth.uuid,
    BigInt(auth.amount),
    auth.signerAddress as `0x${string}`,
    BigInt(auth.expiresAt),
    auth.signature as `0x${string}`,
  ],
  account: auth.signerAddress as `0x${string}`,
});

console.log('Fee claim submitted:', txHash);

Fee States

Fees progress through the following states:

State	Description
Pending	Fees from trades that haven’t been confirmed yet
Locked	Fees locked for payout (awaiting operator settlement)
Unclaimed	Fees available to claim via the vault contract

Only unclaimed fees can be claimed. Pending and locked fees will become claimable after the settlement process completes.

Error Handling

try {
  const txHash = await client.claimDevFees({
    walletClient,
    publicClient,
  });
  console.log('Success:', txHash);
} catch (error) {
  if (error instanceof Error) {
    if (error.message.includes('devFlags required')) {
      console.error('Client not configured with devFlags');
    } else if (error.message.includes('No unclaimed fees')) {
      console.error('No fees available to claim');
    } else if (error.message.includes('pending fee claim signature')) {
      console.error('A claim is already in progress. Wait for it to expire.');
    } else if (error.message.includes('Signature expired')) {
      console.error('Auth signature expired, try again');
    } else if (error.message.includes('User rejected')) {
      console.error('User cancelled transaction');
    } else {
      console.error('Claim failed:', error.message);
    }
  }
}

Important Notes

All fee amounts are in µUSDC (6 decimal places: 1 USDC = 1,000,000 µUSDC)
Fee claim authorizations expire after 30 seconds
You can only have one pending claim authorization at a time
Fees are paid out to the signer address configured for your dev account
Use getDevAccountFees to check your balance before attempting to claim
The SDK automatically handles EIP-712 authentication when devFlags is configured

TypeScript SDK

​Overview

​Configuration

​Getting Account Info

​getDevAccountInfo

​Returns

​Example

​Checking Fee Balances

​getDevAccountFees

​Returns

​Example

​Fee Claim History

​getDevFeeClaimHistory

​Parameters

​Returns

​Example

​Claiming Fees

​claimDevFees

​Parameters

​Returns

​Example

​Low-Level Authorization

​getFeeClaimAuthorization

​Example

​Fee States

​Error Handling

​Important Notes

Overview

Configuration

Getting Account Info

`getDevAccountInfo`

Returns

Example

Checking Fee Balances

`getDevAccountFees`

Returns

Example

Fee Claim History

`getDevFeeClaimHistory`

Parameters

Returns

Example

Claiming Fees

`claimDevFees`

Parameters

Returns

Example

Low-Level Authorization

`getFeeClaimAuthorization`

Example

Fee States

Error Handling

Important Notes