Skill: aionmarket-trading

Core trading operations for AI agents on AION Market / Polymarket / Kalshi. This skill covers the foundational capabilities — agent lifecycle, wallet setup, market data, order execution, and position management.

Strategy skills (market discovery, signal generation, automated loops) are separate skills that build on top of this one.

---

Scope

• Applies to: Any AI agent that needs to trade prediction markets through AION Market
• Does NOT cover: Strategy logic, autonomous market scanning loops, or signal generation (see dedicated strategy skills)

---

Prerequisites — USER MUST PROVIDE

Before this skill can operate, the user must supply:

Secret	Where to set	Example
Agent API Key	AIONMARKET_API_KEY env var or .env	sk_live_Ab12Cd34...
Wallet Private Key	WALLET_PRIVATE_KEY env var or .env	0xabc123... (64 hex chars, Polygon)
Solana Private Key	SOLANA_PRIVATE_KEY env var or .env	<base58-key> (Kalshi optional)

The skill will:

1. Derive wallet addresses from provided keys (Polygon and/or Solana)
2. For Polymarket, call CLOB auth to derive API Key / Secret / Passphrase from private key signature
3. Register Polymarket CLOB credentials with AION Market via register_wallet_credentials() when needed
4. For Kalshi, use quote -> local sign -> submit flow via DFlow-backed endpoints
5. Automatically check wallet readiness before trading: balance, gas/fees, allowance (Polymarket), and market context

If the private key is missing, STOP and ask the user to provide it. Never guess, fabricate, or skip credential setup. Store secrets in a local .env file (never commit to git) or export as env vars.

---

Assumptions

• Python 3.9+
• aion-sdk >= 0.1.2 installed (pip install aion-sdk)
• py-clob-client for Polymarket order signing and credential derivation
• Agent has been registered or will be registered as part of the flow
• Polymarket CLOB credentials are derived automatically from private key via py-clob-client
• Kalshi trading uses quote -> sign -> submit; position queries use the unified get_current_positions(..., venue="kalshi") endpoint
• All SDK methods return plain dicts/lists; errors raise ApiError
• get_markets() returns events with nested markets[] sub-markets — trading fields like conditionId, clobTokenIds, outcomePrices live on the sub-market, not the event

---

Principles

1. Always check context before trading — call get_market_context() before every order
2. Never trade without a thesis — every trade needs explicit reasoning
3. Respect risk limits — honour riskLimit, maxTradesPerDay, maxTradeAmount
4. Fail loudly — catch ApiError and surface the message; never swallow errors
5. Self-custody — wallet keys belong to the user; SDK only stores encrypted CLOB credentials
6. Automate mechanical steps — do not ask the user to manually confirm balance checks, gas checks, allowance checks, or approval after the private key is available
7. Verify execution independently — if the wrapper response is weak, validate through the corresponding venue (Polymarket or Kalshi) before reporting failure

---

Automation Defaults

Unless the user explicitly overrides them, the agent should use these defaults:

• default trade mode: market
• default buy size: 2 USDC
• default behavior: auto-select a valid market candidate from the requested strategy scope
• default pre-trade workflow: derive wallet, register wallet credentials, check balance, check gas, check allowance, auto-approve if needed, then trade
• default post-trade workflow: query recent venue-specific trades/orders (Polymarket orders or Kalshi positions/orders) if the SDK result is generic, null, or ambiguous

The agent should ask the user only for information it cannot safely infer or execute itself.

---

Constraints

MUST

• Set AIONMARKET_API_KEY before any authenticated call
• Register Polymarket CLOB credentials before live Polymarket trading
• Check wallet balance, gas/fees, and relevant allowance before submitting any order
• Call get_market_context() before placing any trade
• Handle ApiError on every SDK call
• Save the API key returned by register_agent() immediately — it is shown only once
• For Polymarket, send a full signed order object and walletAddress with every trade
• For Kalshi, follow quote -> local sign -> submit and include userPublicKey when executing BUY flows
• Verify downstream execution via the target venue when SDK responses are incomplete- Charge platform trading fee after every successful order — call charge_polymarket_fee() or charge_kalshi_fee() after trade confirmation
• Ensure fee allowance is pre-approved before trading — Polymarket requires Safe AllowanceModule delegate; Kalshi requires USDC token approval on Solana

SHOULD

• Use environment variables for all secrets (never hardcode)
• Call get_briefing() periodically (heartbeat pattern) for risk alerts and opportunities
• Set conservative risk limits first via update_settings(), then scale up
• Cancel stale open orders promptly
• Rotate API keys every 90 days
• Prefer market orders for simple one-shot execution unless the user explicitly requests a limit order
• Auto-approve required spenders when allowance is missing and gas is sufficient

AVOID

• Trading without checking warnings from market context
• Exceeding the agent's configured maxTradeAmount
• Sharing or logging API keys, CLOB secrets, or private keys
• Calling cancel_all_orders() without confirming with the user first
• Making trades in markets the agent has not researched
• Treating a wrapper INTERNAL_ERROR as final without checking whether the downstream venue actually accepted or matched the order

---

Installation

pip install aion-sdk py-clob-client python-dotenv

• py-clob-client — Polymarket official SDK, derives CLOB API credentials from private key
• python-dotenv — loads .env file automatically

---

Environment Setup

Create a .env file in your project root (add .env to .gitignore):

# .env
AIONMARKET_API_KEY=sk_live_...
WALLET_PRIVATE_KEY=0xabc123...your_64_hex_char_private_key

# Optional — only set this when AION Market docs tell you to use
# a non-production environment URL for your target environment.
# Do not hardcode a staging URL copied from an old example.
# AIONMARKET_BASE_URL=https://<documented-aionmarket-base-url>/bvapi

Or export directly:

export AIONMARKET_API_KEY="sk_live_..."
export WALLET_PRIVATE_KEY="0xabc123..."

Derive Wallet Address and CLOB Credentials from Private Key

import os
from dotenv import load_dotenv
from py_clob_client.client import ClobClient

load_dotenv()  # loads .env file

private_key = os.environ["WALLET_PRIVATE_KEY"]

# Use Polymarket CLOB client to derive credentials from private key
polymarket = ClobClient(
    "https://clob.polymarket.com",
    key=private_key,
    chain_id=137,
)
creds = polymarket.create_or_derive_api_creds()
# creds contains: api_key, api_secret, api_passphrase

wallet_address = polymarket.get_address()
print(f"Wallet address: {wallet_address}")
print(f"CLOB credentials derived successfully")

Base URL resolution priority:

1. Explicit base_url argument in code
2. AIONMARKET_BASE_URL environment variable
3. Production default: https://www.aionmarket.com//bvapi

Use the SDK's documented resolution order above. Do not hardcode a sandbox or staging URL in sample code unless that exact environment URL is the current one documented by AION Market.

---

Workflow: Agent Bootstrap

Run once to create an agent and bind a wallet.

Step 1 — Register Agent

from aion_sdk import AionMarketClient

client = AionMarketClient()  # no key needed for registration
registration = client.register_agent("my-trading-bot")

api_key = registration["apiKeyCode"]
claim_code = registration["claimCode"]
print(f"API Key (save now!): {api_key}")
print(f"Claim URL: {registration['claimUrl']}")

Save apiKeyCode immediately — it is only returned once. After the API key is generated, open or click claimUrl and complete the claim/auth flow. Generating the key alone does not finish agent authentication.

The claimUrl returned by register_agent() is environment-aware and points directly to the frontend claim page (staging or production). Open it in a browser to claim and authenticate the agent.

The URL format is:

https://<FRONTEND_DOMAIN>/agents/claim?code=<CLAIM_CODE>

Or use claim_preview(claim_code) to verify the agent name before claiming.

Step 2 — Verify Agent

client = AionMarketClient(api_key=api_key)
me = client.get_me()
print(f"Agent: {me['name']}, Status: {me['status']}")

Step 3 — Derive Polymarket CLOB Credentials & Register Wallet

The private key is used to call Polymarket's auth endpoint and derive CLOB credentials automatically. The user does not need to manually copy API Key / Secret / Passphrase from Polymarket settings.

import os
from dotenv import load_dotenv
from py_clob_client.client import ClobClient

load_dotenv()

private_key = os.environ["WALLET_PRIVATE_KEY"]

# 1. Derive CLOB credentials from private key via Polymarket
polymarket = ClobClient(
    "https://clob.polymarket.com",
    key=private_key,
    chain_id=137,
)
creds = polymarket.create_or_derive_api_creds()
wallet = polymarket.get_address()

print(f"Wallet: {wallet}")
print(f"CLOB API Key: {creds.api_key}")

# 2. Register with AION Market
check = client.check_wallet_credentials(wallet)
if not check["hasCredentials"]:
    client.register_wallet_credentials(
        wallet_address=wallet,
        api_key=creds.api_key,
        api_secret=creds.api_secret,
        api_passphrase=creds.api_passphrase,
    )
    print(f"Wallet credentials registered for {wallet}")
else:
    print(f"Wallet {wallet} already configured.")

Step 4 — Configure Risk Limits

client.update_settings(
    max_trades_per_day=50,
    max_trade_amount=100.0,
    trading_paused=False,
    auto_redeem_enabled=True,
)
settings = client.get_settings()
print(settings)

Step 5 — Kalshi Prerequisites (Optional, for Kalshi venue)

• Ensure Solana wallet is available (SOLANA_PRIVATE_KEY / userPublicKey)
• Use kalshi_quote() to request unsigned tx, locally sign, then call kalshi_submit()
• For BUY flows, provide userPublicKey so KYC/geo checks can be evaluated upstream

---

Workflow: Market Search & Context

Understanding Market Data Structure

Critical: get_markets() returns events, each containing a nested markets[] array of sub-markets. Trading fields like conditionId, clobTokenIds, outcomePrices, negRisk, and orderPriceMinTickSize live on the sub-market, NOT the event.

import ast

# Search returns events
events = client.get_markets(q="bitcoin", limit=10)

for event in events:
    print(f"Event: {event['title']}")
    for sub in event.get("markets", []):
        # Parse JSON strings
        prices = ast.literal_eval(sub.get("outcomePrices", '["0.5","0.5"]'))
        token_ids = ast.literal_eval(sub.get("clobTokenIds", '[]'))
        print(f"  Sub-market: {sub['question']}")
        print(f"    conditionId: {sub['conditionId']}")
        print(f"    YES price: {prices[0]}, NO price: {prices[1]}")
        print(f"    YES token: {token_ids[0] if token_ids else 'N/A'}")
        print(f"    negRisk: {sub.get('negRisk', False)}")
        print(f"    tickSize: {sub.get('orderPriceMinTickSize', 0.01)}")
        print(f"    minSize: {sub.get('orderMinSize', 5)}")

Get Market Context (REQUIRED before trading)

context = client.get_market_context("CONDITION_ID", user=wallet)

print(f"Name:       {context.get('name')}")
print(f"Position:   {context.get('myPosition')}")
print(f"Risk limit: {context.get('riskLimit')}")
print(f"Warnings:   {context.get('warnings')}")

if context.get("warnings"):
    print("⚠️  Review warnings before proceeding!")

Automatic Pre-Trade Readiness Checks

Before signing or submitting any order, the agent should automatically verify:

• wallet credentials are already registered, otherwise register them
• collateral balance is sufficient for the intended spend
• Polygon gas balance is sufficient if an onchain approval may be needed
• the required spender allowance already exists for the intended order

If allowance is insufficient and gas is available, the agent should send the approval transaction automatically instead of asking the user to do it manually.

---

Workflow: Trade Execution

Building a Signed Order (REQUIRED)

The trade() endpoint requires a complete EIP712-signed order from py-clob-client. Passing "order": {} will cause a credential lookup failure — the server reads order.signatureType to find your wallet credentials.

import ast
from py_clob_client.client import ClobClient
from py_clob_client.clob_types import ApiCreds, CreateOrderOptions, OrderArgs

# 1. Initialize CLOB client with creds (derived earlier in bootstrap)
clob = ClobClient(
    "https://clob.polymarket.com",
    key=private_key,     # WALLET_PRIVATE_KEY
    chain_id=137,
    creds=ApiCreds(
        api_key=creds.api_key,
        api_secret=creds.api_secret,
        api_passphrase=creds.api_passphrase,
    ),
)

# 2. Extract trading params from sub-market (NOT event)
sub_market = event["markets"][0]  # pick the sub-market you want to trade
condition_id = sub_market["conditionId"]
token_ids = ast.literal_eval(sub_market["clobTokenIds"])
yes_token_id = token_ids[0]   # index 0 = YES, index 1 = NO
no_token_id = token_ids[1]
neg_risk = sub_market.get("negRisk", False)
tick_size = str(sub_market.get("orderPriceMinTickSize", "0.01"))
min_size = sub_market.get("orderMinSize", 5)

# 3. Build signed order — MUST use CreateOrderOptions for proper signing
signed_order = clob.create_order(
    OrderArgs(
        token_id=yes_token_id,   # or no_token_id for NO side
        price=0.55,
        size=min_size,           # must >= orderMinSize
        side="BUY",
    ),
    options=CreateOrderOptions(
        tick_size=tick_size,     # from sub-market.orderPriceMinTickSize
        neg_risk=neg_risk,       # CRITICAL for neg-risk markets!
    ),
)

# 4. Convert dataclass to dict for JSON serialization
order_dict = signed_order.dict()

Place a Trade

result = client.trade({
    "marketConditionId": condition_id,          # hex conditionId from sub-market
    "marketQuestion": sub_market["question"],   # question text
    "outcome": "YES",                           # YES or NO
    "orderSize": min_size,                      # number of contracts
    "price": 0.55,                              # price per contract (0-1)
    "isLimitOrder": True,                       # True=limit, False=market
    "order": order_dict,                        # ← FULL signed order (never {})
    "walletAddress": wallet,                    # ← REQUIRED
    "reasoning": "Strategy edge explanation",
})
print(f"Order ID: {result.get('orderId')}")
print(f"Status:   {result.get('status')}")

Default Execution Policy

For general-purpose execution, use this default policy unless the user overrides it:

1. prefer market mode
2. use 2 USDC as default buy size
3. derive a marketable cap from current prices or order book when using market-order helpers
4. ask for a price only when the user explicitly requested a limit order and did not provide one
5. report the market snapshot and final order parameters without blocking on extra confirmation

Common pitfalls:

• "order": {} → server cannot find signatureType, returns credential error
• Using event numeric ID as marketConditionId → use sub-market hex conditionId
• Missing walletAddress → "walletAddress 不能为空" error
• Not setting neg_risk=True for neg-risk markets → invalid signature, Polymarket rejects
• orderSize below orderMinSize → order rejected
• Insufficient USDC balance → server returns generic INTERNAL_ERROR
• Insufficient allowance → downstream exchange cannot spend collateral
• SDK result is empty or generic → verify recent trades and orders before reporting failure

Order types: GTC (default), FOK, GTD, FAK Sides: BUY, SELL Outcomes: YES, NO

---

Workflow: Kalshi Quote -> Sign -> Submit

Use this flow for Kalshi venue execution.

quote = client.kalshi_quote(
    market_ticker="KX...",
    side="YES",
    action="BUY",
    amount=10,
    user_public_key="<solana-wallet>",
)

# Sign quote["unsignedTransaction"] locally (wallet implementation specific)
signed_tx = "<base64-signed-tx>"

submit = client.kalshi_submit(
    market_ticker="KX...",
    side="YES",
    action="BUY",
    amount=10,
    quote_id=quote["quoteId"],
    signed_transaction=signed_tx,
    user_public_key="<solana-wallet>",
    in_amount=quote.get("inAmount"),
    out_amount=quote.get("outAmount"),
    min_out_amount=quote.get("minOutAmount"),
)
print(submit)

# Unified positions endpoint for Kalshi (venue = kalshi)
kalshi_positions = client.get_current_positions(
    user="<solana-wallet>",
    venue="kalshi",
)
print(kalshi_positions)

Kalshi currently does not expose a dedicated cancel API in this SDK. Use a SELL flow (kalshi_quote -> sign -> kalshi_submit) to reduce/exit exposure.

---

Workflow: Platform Fee Charging

AION Market charges a 1% platform trading fee on every executed order. This fee is mandatory and must be collected after each successful trade. The agent should handle this automatically as part of the post-trade workflow.

Fee Structure

Venue	Fee Rate	Token	Chain	Collection Method
Polymarket	1% of notional (orderSize × price)	pUSD	Polygon	Safe AllowanceModule (auto-cron or manual)
Kalshi	1% of order amount	USDC (SPL)	Solana	Fireblocks transfer (manual trigger)

Fee Calculation

Polymarket: fee = orderSize × price × 0.01
Kalshi:     fee = orderAmount × 0.01

Example: An order of 100 contracts at $0.55 → notional = $55 → fee = $0.55 pUSD

Platform Fee Receiving Addresses

Venue	Platform Wallet
Polymarket (Polygon)	0xeA44cAF1f893729342dC5D8903F658E8D3e2379B
Kalshi (Solana)	CHMkL5utJWFFHSkHX6pwWcb8VXj5jAz5fAqqMGAyEXcX

Prerequisites for Fee Collection

Polymarket (pUSD on Polygon):

1. User's Safe wallet must have AllowanceModule enabled
2. Platform Fireblocks address must be added as delegate in the AllowanceModule
3. Sufficient pUSD token allowance must be configured on the module
4. The agent should verify allowance before trading and auto-approve if gas is available

Kalshi (USDC on Solana):

1. User's Solana wallet must hold sufficient USDC (native SPL token)
2. User must grant token approval to the platform vault address
3. The agent should use the local private key to sign approval if not already granted

Post-Trade Fee Charging Flow

Polymarket — Automatic + Manual Fallback

Polymarket fees are collected automatically by a server-side cron job (every 3 seconds). However, the agent should verify fee status and trigger manually if needed:

# After a successful trade:
result = client.trade({...})
order_hash_id = result.get("orderId")

# Option 1: Rely on automatic cron (default — fees are charged within 3 seconds)
# Option 2: Explicitly trigger fee charging
if order_hash_id:
    fee_result = client.charge_polymarket_fee(order_hash_id)
    print(f"Fee: ${fee_result['feeAmount']}, Status: {fee_result['status']}")
    # status will be 'PENDING' — Fireblocks tx takes ~10-30s to confirm

Kalshi — Must Trigger Manually

Kalshi fees are NOT collected automatically. The agent MUST call charge_kalshi_fee() after a successful kalshi_submit():

# After successful Kalshi submit:
submit_result = client.kalshi_submit(
    market_ticker="KX...",
    side="YES",
    action="BUY",
    amount=10,
    signed_transaction=signed_tx,
    quote_id=quote["quoteId"],
    user_public_key=sol_wallet,
)

tx_signature = submit_result.get("txSignature")

# REQUIRED: Charge the 1% platform fee
if tx_signature:
    fee_result = client.charge_kalshi_fee(tx_signature)
    print(f"Fee: ${fee_result['feeAmount']}, TxId: {fee_result['transactionId']}")

Fee Charging Error Handling

from aion_sdk import ApiError

try:
    fee_result = client.charge_kalshi_fee(tx_signature)
except ApiError as e:
    if "allowance" in e.message.lower() or "insufficient" in e.message.lower():
        print("❌ Insufficient allowance — user needs to approve more USDC")
    elif "not found" in e.message.lower():
        print("❌ Order not found — verify order was submitted successfully")
    else:
        print(f"❌ Fee charging failed: {e.message}")

Agent Commission

Agents that execute trades earn a 10% commission on collected fees:

• Platform collects 1% fee → agent receives 0.1% of trade notional
• Commission is tracked automatically and available for periodic payout
• No additional API calls are needed — commission is recorded when fee is charged

---

Workflow: Order Management

# List open orders
open_orders = client.get_open_orders()

# Order history (with optional filters)
history = client.get_order_history(limit=20, order_status=2)

# Single order detail
detail = client.get_order_detail("ORDER_ID")

# Cancel one order
client.cancel_order("ORDER_ID")

# Cancel ALL orders (use with care)
client.cancel_all_orders()

---

Workflow: Heartbeat / Briefing

Call periodically (every 30s–15min depending on strategy frequency).

# wallet can be Polygon or Solana based on venue flow
briefing = client.get_briefing(user=wallet)

# 1. Handle risk alerts first
for alert in briefing.get("riskAlerts", []):
    print(f"⚠️  {alert}")

# 2. Review open orders
open_orders = client.get_open_orders()
print(f"Open orders: {len(open_orders)}")

# 3. Scan opportunity markets
for opp in briefing.get("opportunityMarkets", [])[:5]:
    print(f"Opportunity: {opp.get('id')} — {opp.get('question')}")

---

Workflow: Redemption

When a market settles, redeem winning positions:

client.redeem(market_id="MARKET_ID", side="YES")

---

Error Handling

from aion_sdk import AionMarketClient, ApiError

client = AionMarketClient()

try:
    result = client.get_me()
except ApiError as e:
    if e.status_code == 401:
        print("❌ Invalid or missing API key")
    elif e.status_code == 403:
        print("❌ Agent not authorized — check claim status or wallet credentials")
    elif e.status_code == 429:
        print("⏳ Rate limited — back off and retry")
    else:
        print(f"API Error {e.code}: {e.message}")

When trading, an ApiError from AION Market may still hide a successful downstream venue execution. If the response is ambiguous, query venue-specific follow-up endpoints before concluding failure (Polymarket orders/trades, or Kalshi submit/positions state).

---

SDK Method Reference

Agent Management

Method	Description
register_agent(name)	Create agent, returns API key + claim code
claim_preview(claim_code)	Preview agent info via claim code
get_me()	Current agent profile and balances
get_settings()	Read risk control settings
update_settings(...)	Update max trades, max amount, pause, auto-redeem
get_skills(category, limit, offset)	List available strategy skills

Market Operations

Method	Description
get_markets(q, limit, page, venue, events_status)	Search markets by keyword
get_market(market_id, venue)	Single market details
check_market_exists(market_id, venue)	Existence check
get_prices_history(token_id, ...)	Historical prices for a token
get_briefing(venue, since, user, include_markets)	Heartbeat: alerts + opportunities
get_market_context(market_id, venue, user, my_probability)	Pre-trade context & risk
get_current_positions(user, venue, ...)	Unified current positions (polymarket / kalshi)

Wallet Management

Method	Description
check_wallet_credentials(wallet_address)	Check if CLOB credentials exist
register_wallet_credentials(wallet_address, api_key, api_secret, api_passphrase)	Store encrypted CLOB credentials

Trading Operations

Method	Description
trade(payload)	Place a Polymarket market/limit order
get_open_orders(venue, market_condition_id, limit)	List unfilled orders
get_order_history(venue, ..., limit, offset)	Historical orders with filters
get_order_detail(order_id, venue, wallet_address)	Single order detail
cancel_order(order_id, venue, wallet_address)	Cancel one order
cancel_all_orders(venue, wallet_address)	Cancel all open orders
redeem(market_id, side, venue, wallet_address)	Redeem settled position
kalshi_quote(...)	Build unsigned Kalshi quote tx
kalshi_submit(...)	Submit locally signed Kalshi tx

Fee Charging Operations

Method	Description
charge_polymarket_fee(order_hash_id)	Charge 1% fee for Polymarket order (pUSD on Polygon)
charge_kalshi_fee(kalshi_order_id)	Charge 1% fee for Kalshi order (USDC on Solana)

---

Checklist: Ready to Trade

• pip install aion-sdk py-clob-client python-dotenv installed
• .env file created with AIONMARKET_API_KEY and WALLET_PRIVATE_KEY (plus SOLANA_PRIVATE_KEY if using Kalshi)
• .env added to .gitignore
• get_me() returns valid agent info
• Polymarket CLOB credentials derived from private key and registered via register_wallet_credentials()
• automatic balance, gas/fees, and allowance checks are part of the trading flow
• missing allowance is auto-approved when technically possible
• Risk limits configured via update_settings()
• Heartbeat loop (get_briefing()) running or planned
• Error handling wraps every SDK call with ApiError
• For Kalshi: quote -> sign -> submit flow validated with kalshi_quote() / kalshi_submit()
• ambiguous trade responses are verified against venue-specific state endpoints
• Fee allowance configured — Polymarket Safe AllowanceModule delegate set; Kalshi USDC approval granted
• Post-trade fee charging integrated — charge_polymarket_fee() or charge_kalshi_fee() called after every successful trade

Once all boxes are checked, the agent is ready for strategy skills to drive market discovery and automated trade execution.