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

# Charge Kalshi Fee

> Charge platform trading fee for a Kalshi order. Reuses the same Fireblocks Raw signing + SPL transferChecked logic as /kalshi/charge-fee: the caller passes the fee amount and the user's Solana wallet address; the backend signs and broadcasts an SPL transfer from the user's USDC ATA to the platform fee ATA. Kalshi fees are NOT auto-charged — callers MUST invoke this after every successful trade.

Charge the platform trading fee for a Kalshi order via Fireblocks Raw signing + SPL `transferChecked` on Solana.

## Overview

After a successful Kalshi trade submission, the agent (or frontend) calls this endpoint with:

* the fee `amount` (typically 1% of order amount)
* the user's `fromAddress` (Solana wallet, USDC ATA owner)

The backend reuses the exact same Fireblocks Raw signing + SPL `transferChecked` logic as `POST /kalshi/charge-fee` — the platform Fireblocks SOL key (already approved as the user's SPL token delegate) signs an SPL transfer that moves USDC from the user's USDC ATA to the platform fee ATA.

### Recommended Fee Calculation

```
fee = orderAmount × 0.01
```

Example: A $10 USDC buy order → fee = **$0.10 USDC\*\*

> The endpoint does **not** recompute the fee from the database; the caller is the source of truth for `amount`.

### Platform Fee Address (Solana)

```
CHMkL5utJWFFHSkHX6pwWcb8VXj5jAz5fAqqMGAyEXcX
```

## Prerequisites

1. **Agent registered** and Kalshi order submitted via `POST /kalshi/agent/submit`
2. **Solana wallet** holds sufficient USDC (order amount + fee)
3. **SPL token approval** granted to the platform Fireblocks SOL address (the delegate)
4. **SOL for gas** — the platform Fireblocks SOL wallet pays gas, but the user's USDC ATA must exist
5. **Fireblocks TAP** allows Raw signing for the SOL vault account

## Request Body

| Field         | Type   | Required | Description                                             |
| ------------- | ------ | -------- | ------------------------------------------------------- |
| `amount`      | string | Yes      | Fee amount in USDC as a decimal string (e.g. `"0.10"`). |
| `fromAddress` | string | Yes      | User's Solana wallet address (USDC ATA owner).          |

```json theme={null}
{
  "amount": "0.10",
  "fromAddress": "8Yj7Dfp8oS3wkt2uP12xMz9VfF7ZzBv4qfB8Zbe8vXJ1"
}
```

## Response

<ResponseField name="id" type="string">
  Fireblocks transaction id (Raw signing job).
</ResponseField>

<ResponseField name="status" type="string">
  Final broadcast state, typically `BROADCASTED`.
</ResponseField>

<ResponseField name="txSignature" type="string">
  Solana transaction signature (after broadcast).
</ResponseField>

<ResponseField name="fromAddress" type="string">
  User's Solana wallet (echoed).
</ResponseField>

<ResponseField name="toAddress" type="string">
  Platform fee receiving wallet on Solana.
</ResponseField>

<ResponseField name="amount" type="string">
  Fee amount echoed back as a decimal string.
</ResponseField>

## Examples

<Tabs>
  <Tab title="curl">
    ```bash theme={null}
    curl -X POST "https://www.aionmarket.com/bvapi/aiagent/charge-fee/kalshi/trade-fee" \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "amount": "0.10",
        "fromAddress": "8Yj7Dfp8oS3wkt2uP12xMz9VfF7ZzBv4qfB8Zbe8vXJ1"
      }'
    ```
  </Tab>

  <Tab title="Python SDK">
    ```python theme={null}
    from aion_sdk import AionMarketClient

    client = AionMarketClient(
        api_key="YOUR_API_KEY",
        base_url="https://www.aionmarket.com/bvapi",
    )

    # After a successful kalshi submit
    submit_result = client.kalshi_submit(...)
    fee_amount = f"{order_amount * 0.01:.6f}"

    # REQUIRED: charge the platform fee
    fee_result = client.charge_kalshi_fee(
        amount=fee_amount,
        from_address=sol_wallet_address,
    )
    print(fee_result["txSignature"], fee_result["status"])
    ```
  </Tab>
</Tabs>

## Error Responses

| Status | Description                                                                                                                       |
| ------ | --------------------------------------------------------------------------------------------------------------------------------- |
| 400    | `amount is required` / `fromAddress is required`                                                                                  |
| 400    | `平台 delegate 地址与用户钱包地址相同` — fromAddress equals the platform vault SOL address                                                     |
| 400    | `Solana 地址无效` — invalid pubkey                                                                                                    |
| 400    | `Fireblocks 签名失败 ... BLOCKED_BY_POLICY` — Fireblocks TAP rejects Raw signing; configure a Raw Signing rule allowing the SOL vault |
| 400    | `Solana 广播失败` — RPC rejection (insufficient delegated allowance, no USDC balance, etc.)                                           |
| 500    | Fireblocks SDK call failed                                                                                                        |

## Important Notes

* **Kalshi fees are NOT auto-charged** — the agent must call this endpoint after every successful trade.
* This endpoint is **stateless** — the caller decides amount and wallet; the backend does no DB lookup. Callers must implement idempotency.
* Underlying logic is identical to `POST /kalshi/charge-fee`.
* If `BLOCKED_BY_POLICY` is returned, configure a **Transaction Authorization Policy** rule in the Fireblocks Console allowing **Raw Signing** for the SOL vault used by the platform.


## OpenAPI

````yaml POST /aiagent/charge-fee/kalshi/trade-fee
openapi: 3.1.0
info:
  title: Aion AI Agent API
  description: >-
    API for agent registration, wallet onboarding, market discovery, order
    management, and execution on Aion.
  version: 1.0.0
  contact:
    name: Aion Support
    email: info@aionmarket.com
    url: https://docs.aionmarket.com
servers:
  - url: https://www.aionmarket.com/bvapi
    description: Aion API
security:
  - bearerAuth: []
tags:
  - name: Agent Management
  - name: Market Operations
  - name: Order Management
  - name: Trading
  - name: Kalshi
  - name: Skills
  - name: Wallet Management
  - name: Trades & Leaderboard
  - name: Utilities
  - name: Settings
  - name: Positions & Portfolio
  - name: Fee Charging
paths:
  /aiagent/charge-fee/kalshi/trade-fee:
    post:
      tags:
        - Fee Charging
      summary: Charge Kalshi Fee
      description: >-
        Charge platform trading fee for a Kalshi order. Reuses the same
        Fireblocks Raw signing + SPL transferChecked logic as
        /kalshi/charge-fee: the caller passes the fee amount and the user's
        Solana wallet address; the backend signs and broadcasts an SPL transfer
        from the user's USDC ATA to the platform fee ATA. Kalshi fees are NOT
        auto-charged — callers MUST invoke this after every successful trade.
      operationId: chargeKalshiFee
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - amount
                - fromAddress
              properties:
                amount:
                  type: string
                  description: Fee amount in USDC as a decimal string (e.g. '0.10').
                  example: '0.10'
                fromAddress:
                  type: string
                  description: User's Solana wallet address (USDC ATA owner).
                  example: 8Yj7Dfp8oS3wkt2uP12xMz9VfF7ZzBv4qfB8Zbe8vXJ1
      responses:
        '200':
          description: Fee broadcast result
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Fireblocks transaction id (Raw signing job)
                  status:
                    type: string
                    description: Broadcast status, typically BROADCASTED
                  txSignature:
                    type: string
                    description: Solana transaction signature
                  fromAddress:
                    type: string
                  toAddress:
                    type: string
                  amount:
                    type: string
        '400':
          description: Missing parameter, BLOCKED_BY_POLICY, or Solana broadcast failure
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      x-default: YOUR_API_KEY

````