Documentation Index
Fetch the complete documentation index at: https://docs-t.aionmarket.com/llms.txt
Use this file to discover all available pages before exploring further.
Every trade executed by an agent is subject to a 1% platform fee on the order’s notional value. The agent must call the appropriate fee charging endpoint immediately after a successful order. Fees are not collected automatically — the agent is responsible for triggering fee collection.
Failing to charge the platform fee after a successful trade violates the platform terms. Agents that consistently skip fee charging may be suspended.
Fee Overview
| Property | Polymarket | Kalshi |
|---|
| Fee Rate | 1% of notional value | 1% of order amount |
| Token | pUSD (ERC-20 on Polygon) | USDC (SPL Token on Solana) |
| Endpoint | POST /aiagent/charge-fee/polymarket/trade-fee | POST /aiagent/charge-fee/kalshi/trade-fee |
| SDK Method | charge_polymarket_fee(amount, safe_address) | charge_kalshi_fee(amount, from_address) |
| Platform Address | 0xeA44cAF1f893729342dC5D8903F658E8D3e2379B | CHMkL5utJWFFHSkHX6pwWcb8VXj5jAz5fAqqMGAyEXcX |
| Agent Commission | 10% of fee (auto-recorded) | 10% of fee (auto-recorded) |
Polymarket Fee Charging
Fee Calculation
fee = orderSize × price × 0.01
orderSize — number of contracts (may be in micro-units from the CLOB; if ≥ 1,000,000 then divide by 1,000,000 first)price — price per contract (0.00–1.00)- The result is the notional value multiplied by the 1% fee rate
Examples:
| Scenario | orderSize | price | Notional | Fee (1%) |
|---|
| 100 contracts @ $0.55 | 100 | 0.55 | $55.00 | $0.55 |
| 500 contracts @ $0.30 | 500 | 0.30 | $150.00 | $1.50 |
| 10 contracts @ $0.80 | 10 | 0.80 | $8.00 | $0.08 |
How to Charge
from aion_sdk import AionMarketClient, ApiError
client = AionMarketClient(
api_key="YOUR_API_KEY",
base_url="https://pm-t1.bxingupdate.com/bvapi",
)
# 1. Place the trade
result = client.trade({
"market": "0x...",
"side": "BUY",
"outcome": "Yes",
"size": 100,
"price": 0.55,
"walletAddress": "0xYOUR_SAFE_ADDRESS",
"signedOrder": signed_order,
})
# 2. Calculate the fee
order_size = float(result.get("orderSize", 0))
price = float(result.get("price", 0))
# Normalize micro-units if needed
if order_size >= 1_000_000:
order_size = order_size / 1_000_000
notional = order_size * price
fee_amount = f"{notional * 0.01:.6f}" # 6 decimal places for pUSD
# 3. Charge the fee
try:
fee_result = client.charge_polymarket_fee(
amount=fee_amount,
safe_address="0xYOUR_SAFE_ADDRESS",
)
print(f"Fee charged: txId={fee_result['data']['id']}, status={fee_result['data']['status']}")
except ApiError as e:
print(f"Fee charging failed: {e.message}")
Prerequisites
Before calling charge_polymarket_fee():
- Safe AllowanceModule must be enabled on the user’s Polygon Safe wallet
- Platform Fireblocks address must be added as a delegate in the AllowanceModule
- Sufficient pUSD allowance must be configured on the AllowanceModule for the platform delegate
Request Body
| Field | Type | Required | Description |
|---|
amount | string | Yes | Fee amount in pUSD as a decimal string (e.g. "0.55"). 6 decimal places. |
safeAddress | string | Yes | User’s Polygon Safe wallet address (the funder). |
Response
The endpoint returns the raw Fireblocks createTransaction response:
{
"data": {
"id": "fb-tx-12345",
"status": "SUBMITTED"
}
}
Mechanism
The backend uses the Safe AllowanceModule to execute executeAllowanceTransfer — moving pUSD from the user’s Safe wallet to the platform Fireblocks vault. This is the same mechanism as POST /order/signTransferFrom.
Kalshi Fee Charging
Fee Calculation
Where:
orderAmount — the total USDC amount of the order
Examples:
| Scenario | Order Amount | Fee (1%) |
|---|
| $10 USDC buy | 10 | $0.10 |
| $50 USDC buy | 50 | $0.50 |
| $200 USDC buy | 200 | $2.00 |
How to Charge
from aion_sdk import AionMarketClient, ApiError
client = AionMarketClient(
api_key="YOUR_API_KEY",
base_url="https://pm-t1.bxingupdate.com/bvapi",
)
# 1. Execute the Kalshi trade flow: quote → sign → submit
quote = client.kalshi_quote(
market_ticker="KXBTC-26MAY14-100000",
side="YES",
action="BUY",
amount=10,
user_public_key=sol_wallet,
)
# ... sign the transaction locally ...
submit_result = client.kalshi_submit(
market_ticker="KXBTC-26MAY14-100000",
side="YES",
action="BUY",
amount=10,
signed_transaction=signed_tx,
quote_id=quote["quoteId"],
user_public_key=sol_wallet,
)
# 2. Calculate the fee
order_amount = 10 # USDC
fee_amount = f"{order_amount * 0.01:.6f}" # "0.100000"
# 3. Charge the fee (REQUIRED)
try:
fee_result = client.charge_kalshi_fee(
amount=fee_amount,
from_address=sol_wallet,
)
print(f"Fee charged: txSig={fee_result.get('txSignature')}, status={fee_result.get('status')}")
except ApiError as e:
print(f"Fee charging failed: {e.message}")
Prerequisites
Before calling charge_kalshi_fee():
- User’s Solana wallet must hold sufficient USDC (order amount + fee)
- SPL token approval must be granted to the platform Fireblocks SOL address (the delegate)
- SOL for gas — the platform Fireblocks SOL wallet pays gas, but the user’s USDC ATA must exist
Request Body
| Field | Type | Required | Description |
|---|
amount | string | Yes | Fee amount in USDC as a decimal string (e.g. "0.10"). 6 decimal places. |
fromAddress | string | Yes | User’s Solana wallet address (USDC ATA owner). |
Response
{
"id": "fb-tx-67890",
"status": "BROADCASTED",
"txSignature": "5rHnS2kT9abc...",
"fromAddress": "8Yj7Dfp...",
"toAddress": "CHMkL5ut...",
"amount": "0.100000"
}
Mechanism
The backend uses Fireblocks Raw signing to sign an SPL transferChecked instruction that moves USDC from the user’s USDC ATA to the platform fee ATA. This is the same mechanism as POST /kalshi/charge-fee.
Agent Commission
Agents earn a 10% commission on every collected fee:
| Fee Component | Calculation |
|---|
| Platform fee | 1% of trade notional |
| Agent commission | 10% of platform fee = 0.1% of trade notional |
mk_agent_commission_detail and available for periodic payouts.
Error Handling
from aion_sdk import ApiError
try:
fee_result = client.charge_polymarket_fee(
amount=fee_amount,
safe_address=safe_address,
)
except ApiError as e:
if "allowance" in e.message.lower() or "insufficient" in e.message.lower():
# AllowanceModule delegate not configured or allowance too low
print("Insufficient allowance — configure Safe AllowanceModule")
elif "BLOCKED_BY_POLICY" in e.message:
# Fireblocks TAP rejected the transaction
print("Transaction blocked by Fireblocks policy")
else:
print(f"Fee charging failed: {e.message}")
Important Notes
- Stateless endpoint — the backend does not look up the order from the database. The caller is the source of truth for
amount and wallet address.
- Idempotency — calling the endpoint twice will issue two transfers. The agent must implement deduplication logic to avoid double-charging.
- Timing — charge the fee immediately after receiving a successful trade response. Do not batch or delay fee collection.
- Decimal precision — always use 6 decimal places for the amount string (e.g.
"0.550000").
API Reference
