核心特点

支持的链与代币

私钥同时控制 Axon / BSC / Arbitrum 上的同一地址。卖方需 AXON + gas；买方只需 USDT/USDC + BNB/ETH gas。

交易流程

订单状态

快速开始

bashcopy
pip install web3 eth-account

pythoncopy
import os
from src.otc_client import OTCClient

client = OTCClient(
    private_key=os.environ["AXON_PRIVATE_KEY"],
    contract_address=os.environ["OTC_CONTRACT_ADDRESS"],
)

Keeper HTTP API

Base URL: https://axonotc.com · 仅 GET · 链上转账需自行完成

bashcopy
# 健康检查
curl -s "https://axonotc.com/health"

# 获取所有活跃卖单
curl -s "https://axonotc.com/orders"

# 获取订单 #5 详情（含专属付款地址）
curl -s "https://axonotc.com/order/5"

买方操作

list_active_orders()

pythoncopy
orders, total = client.list_active_orders(offset=0, limit=50)
for o in orders:
    print(o)
    # Order#12  100.0000 AXON  @ $0.0200/USDT on BSC  total=2.00 USDT  [Active]

buy_full()

pythoncopy
result = client.buy_full(order_id=12)
print(f"付款地址: {result['payment_address']}")
print(f"付款 tx: {result['payment_tx']}")
# Keeper 自动: 检测付款 → 放 AXON → 转 USDT

buy_full() 内部调用: ① get_payment_info() 获取专属地址 → ② send_payment() 转 USDT → ③ 返回 {payment_address, payment_tx, order}

确认收到 AXON

pythoncopy
import time
time.sleep(30)  # 等 Keeper 处理 (通常 30-60s)
order = client.get_order(12)
print(order.status_label)      # "Completed"
print(client.axon_balance())   # AXON 余额

FAQ

完整示例

buy_axon.pycopy
from src.otc_client import OTCClient
import os

client = OTCClient(
    private_key=os.environ["AXON_PRIVATE_KEY"],
    contract_address=os.environ["OTC_CONTRACT_ADDRESS"],
)

orders, _ = client.list_active_orders(limit=50)
if not orders:
    exit("当前没有卖单")

best = min(orders, key=lambda o: o.price_usd)
print(f"最优: #{best.id}  {best.amount_axon} AXON @ ${best.price_usd}")

bal = client.stablecoin_balance(best.payment_chain_id, best.payment_token)
if bal < best.total_payment:
    exit(f"余额不足: 需 {best.total_payment:.2f}, 有 {bal:.2f}")

result = client.buy_full(best.id)
print(f"付款 tx: {result['payment_tx']}")
print("Keeper 将自动放 AXON 到你的地址")

卖方操作

create_sell_order()

pythoncopy
order_id, tx = client.create_sell_order(
    amount_axon=100,           # 出售数量
    price_usd=0.02,            # 单价 $0.02
    payment_chain_id=56,       # BSC (42161 = Arbitrum)
    payment_token="USDT",      # "USDT" | "USDC"
)
print(f"卖单 #{order_id} 已创建, 总价 {100 * 0.02:.2f} USDT")

可选参数 seller_payment_addr: 指定不同的 BSC/Arb 收款地址（默认同 Axon 地址）。

pythoncopy
order_id, tx = client.create_sell_order(
    amount_axon=100, price_usd=0.02,
    payment_chain_id=56, payment_token="USDT",
    seller_payment_addr="0x你的BSC收款地址",
)

cancel flow

pythoncopy
# step 1: 请求取消 → CancelPending (15min 冷却)
client.request_cancel_order(order_id)

# step 2: 冷却结束后执行取消 → AXON 退回
import time
time.sleep(900)
client.finalize_cancel_order(order_id)

# 如果改变主意:
client.abort_cancel(order_id)  # → 恢复 Active

get_order()

pythoncopy
order = client.get_order(order_id)
print(order.status_label)  # Active | CancelPending | Completed | Cancelled

完整示例

sell_axon.pycopy
from src.otc_client import OTCClient
import os

client = OTCClient(
    private_key=os.environ["AXON_PRIVATE_KEY"],
    contract_address=os.environ["OTC_CONTRACT_ADDRESS"],
)

print(f"AXON 余额: {client.axon_balance():.4f}")

order_id, _ = client.create_sell_order(
    amount_axon=50, price_usd=0.02,
    payment_chain_id=56, payment_token="USDT",
)
print(f"卖单 #{order_id} 已创建")
print("Keeper 自动处理后续，无需任何操作")

查询 API

Order 对象属性

pythoncopy
order = client.get_order(0)

# 核心字段
order.id                  # int     订单 ID
order.seller              # str     卖方地址
order.buyer               # str     买方地址 (成交后)
order.amount_wei          # int     AXON 数量 (wei)
order.amount_axon         # float   AXON 数量 (property)
order.price_per_token     # int     单价 (6-decimal, $7.50 = 7_500_000)
order.price_usd           # float   单价 USD (property)
order.total_payment       # float   总价 (property)
order.payment_chain_id    # int     56 | 42161
order.payment_chain_name  # str     "BSC" | "Arbitrum" (property)
order.payment_token       # str     "USDT" | "USDC"
order.seller_payment_addr # str     卖方收款地址
order.status              # int     0-4
order.status_label        # str     "Active" | "Completed" | ...
order.created_at          # int     创建时间戳
order.cancel_requested_at # int     取消请求时间戳

其他查询

pythoncopy
# 我的订单
my = client.get_my_orders()
my["as_seller"]  # [0, 2, 5]
my["as_buyer"]   # [1, 3]

# 总量
client.get_order_count()

# 余额
client.axon_balance()
client.stablecoin_balance(56, "USDT")
client.stablecoin_balance(42161, "USDC")

方法速查

buyer methods

seller methods

shared methods

合约信息

安全机制

争议处理

异常情况（付款 >5min 未收到 AXON、转错金额等）：

pythoncopy
# 任一方可发起争议
client.raise_dispute(order_id)
# → order.status = Disputed (3)
# → 等待管理员 resolveDispute()

管理员可以：发起争议冻结 → adminForceCancel 退 AXON → 协调退 USDT。联系方式见项目公告渠道。

安全须知

// buyer
✓ 使用 buy_full() 自动获取正确地址和金额
✗ 向 seller_payment_addr 转账 (那是卖方收款地址)
✓ 重复付款时 Keeper 自动退款

// seller
✗ 手动调用 seller_release() (除非已确认链上 USDT 到账)
✓ 挂单后无需操作，Keeper 自动放款

// general
✓ 私钥通过环境变量传入
✗ 硬编码私钥 / 提交 .env 到 git
✓ 手续费 0.3% 从 AXON 扣除，卖方收全额 USDT
✓ 同一私钥控制 Axon/BSC/Arb 地址