> ## 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.

# Developer Fees

> Checking and claiming accumulated dev account fees

## 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

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

## Configuration

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

```typescript theme={null}
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',
  },
});
```

<Warning>
  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.
</Warning>

## Getting Account Info

Retrieve your dev account configuration and settings.

### `getDevAccountInfo`

```typescript theme={null}
async getDevAccountInfo(): Promise<{
  id: string;
  name: string;
  email: string;
  grossFeeBps: string;
  grossBaseFeeUusdc: string;
  bisonFeeCutBps: string;
  payoutChain: string;
  signerAddress: string;
  createdAt: string;
}>
```

#### Returns

<ResponseField name="id" type="string">
  Dev account identifier
</ResponseField>

<ResponseField name="name" type="string">
  Dev account display name
</ResponseField>

<ResponseField name="email" type="string">
  Dev account email
</ResponseField>

<ResponseField name="grossFeeBps" type="string">
  Your fee rate in basis points (100 = 1%)
</ResponseField>

<ResponseField name="grossBaseFeeUusdc" type="string">
  Flat fee per trade in µUSDC (integer string)
</ResponseField>

<ResponseField name="bisonFeeCutBps" type="string">
  Bison's share of your gross fees in basis points
</ResponseField>

<ResponseField name="payoutChain" type="string">
  Chain where fees can be claimed
</ResponseField>

<ResponseField name="signerAddress" type="string">
  Address that will receive fee payouts
</ResponseField>

<ResponseField name="createdAt" type="string">
  Account creation timestamp (ISO 8601)
</ResponseField>

#### Example

```typescript theme={null}
const info = await client.getDevAccountInfo();

console.log('Dev Account:', info.name);
console.log(`  Fee Rate: ${Number(info.grossFeeBps) / 100}%`);
console.log(`  Base Fee: ${Number(info.grossBaseFeeUusdc) / 1_000_000} USDC per trade`);
console.log(`  Bison Cut: ${Number(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`

```typescript theme={null}
async getDevAccountFees(): Promise<{
  id: string;
  name: string;
  pendingFeesUusdc: string;
  lockedFeesUusdc: string;
  unclaimedFeesUusdc: string;
  payoutChain: string;
  signerAddress: string;
}>
```

This method automatically uses your configured `devFlags` for authentication.

#### Returns

<ResponseField name="id" type="string">
  Dev account identifier
</ResponseField>

<ResponseField name="name" type="string">
  Dev account display name
</ResponseField>

<ResponseField name="pendingFeesUusdc" type="string">
  Fees from trades that haven't been confirmed yet (integer string)
</ResponseField>

<ResponseField name="lockedFeesUusdc" type="string">
  Fees locked for payout (awaiting operator settlement, integer string)
</ResponseField>

<ResponseField name="unclaimedFeesUusdc" type="string">
  Fees available to claim via the vault contract (integer string)
</ResponseField>

<ResponseField name="payoutChain" type="string">
  Chain where fees can be claimed
</ResponseField>

<ResponseField name="signerAddress" type="string">
  Address that will receive fee payouts
</ResponseField>

#### Example

```typescript theme={null}
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: ${Number(fees.pendingFeesUusdc) / 1_000_000} USDC`);
console.log(`  Locked: ${Number(fees.lockedFeesUusdc) / 1_000_000} USDC`);
console.log(`  Claimable: ${Number(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`

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

#### Parameters

<ParamField path="limit" type="number">
  Maximum number of claims to return (default: 50, max: 200)
</ParamField>

<ParamField path="cursor" type="string">
  Pagination cursor from a previous response
</ParamField>

#### Returns

<ResponseField name="claims" type="array">
  Array of fee claim records, sorted by most recent first
</ResponseField>

<ResponseField name="claims[].id" type="string">
  Unique identifier for the claim
</ResponseField>

<ResponseField name="claims[].chain" type="string">
  Chain where the claim was processed
</ResponseField>

<ResponseField name="claims[].amountUusdc" type="string">
  Amount claimed in µUSDC (integer string)
</ResponseField>

<ResponseField name="claims[].payoutAddress" type="string">
  Address that received the payout
</ResponseField>

<ResponseField name="claims[].claimedAt" type="string">
  Timestamp when the claim was completed (ISO 8601)
</ResponseField>

<ResponseField name="pagination.total" type="number">
  Number of claims returned in this response
</ResponseField>

<ResponseField name="pagination.hasMore" type="boolean">
  Whether more claims are available
</ResponseField>

<ResponseField name="pagination.nextCursor" type="string">
  Cursor to fetch the next page (only present if hasMore is true)
</ResponseField>

#### Example

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

console.log('Recent fee claims:');
for (const claim of claims) {
  const amount = Number(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.

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

#### Parameters

<ParamField path="walletClient" type="WalletClient" required>
  Viem wallet client for signing transactions
</ParamField>

<ParamField path="publicClient" type="PublicClient" required>
  Viem public client for reading contract state
</ParamField>

#### Returns

Transaction hash of the fee claim transaction.

#### Example

```typescript theme={null}
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 ${Number(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`

```typescript theme={null}
async getFeeClaimAuthorization(): Promise<{
  uuid: string;
  signature: string;
  expiresAt: number;
  amount: string;
  chain: string;
  signerAddress: string;
}>
```

<Warning>
  The authorization expires after 30 seconds. If you don't use it in time, you'll need to request a new one.
</Warning>

#### Example

```typescript theme={null}
import { VAULT_ABI } from '@bison-markets/sdk-ts';

const auth = await client.getFeeClaimAuthorization();

console.log('Fee claim authorization:');
console.log(`  Amount: ${Number(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

```typescript theme={null}
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