| name | aftermath-perpetuals |
| description | Practical skill for integrating Aftermath Perpetuals with native endpoints as the default (full feature set), plus CCXT-compatible endpoints and the TypeScript SDK. |
| version | 2.5.0 |
| capabilities | ["api-integration","sdk-integration","order-placement","position-monitoring","risk-analysis","vault-management","error-handling"] |
Aftermath Perpetuals Skill
Verified against OpenAPI: https://aftermath.finance/api/openapi/spec.json
Last validated: 2026-03-31
Canonical docs UI: https://aftermath.finance/docs
Fast Routing
Choose one file first; do not load everything by default.
Default preference: start with native perpetuals endpoints (/api/perpetuals/*) because they expose the full Aftermath feature set. Use CCXT endpoints when you specifically need exchange-style compatibility.
- CCXT endpoint work ->
ccxt.md
- Native perpetuals endpoint work ->
native.md
- SDK method usage ->
sdk-reference.md
- API failures/retries ->
error-handling.md
- Trading safeguards ->
safety-and-risk.md
- Builder codes/gas pool/referrals/rewards/coins utility routes ->
auxiliary-endpoints.md
- Edge-case pitfalls ->
gotchas.md
Integration Modes
Preferred by default: Native perpetuals (/api/perpetuals/*) for complete API coverage.
| Mode | Best for | Primary file |
|---|
CCXT compatibility (/api/ccxt/*) | Exchange-style payloads and build-sign-submit bots | ccxt.md |
Native perpetuals (/api/perpetuals/*) | Full account/vault previews + tx builders | native.md |
TypeScript SDK (@aftermath-finance/sdk) | Typed app integrations | sdk-reference.md |
High-Risk Guardrails
- Sign
signingDigest, not transactionBytes.
- Keep ID types strict: CCXT write
accountId (object ID) vs native accountId (numeric).
- Treat preview responses as success/error unions.
- Re-sync snapshots after stream reconnect before applying deltas.
- Serialize coin/gas-object-sensitive operations to avoid version conflicts.
Recent API Updates
- Native account/vault routes include
place-scale-order, cancel-and-place-orders, and account share transaction support.
- Account history now includes both
orders (order history) and detailed trades / CSV export routes.
- Margin history requests use
timeframe (1D | 1W | 1M | ALL) with accountId.
- Stop-order data requests support optional
marketIds filtering.
- Vault owner flows include locked-liquidity withdraw routes and a preview route for pausing force-withdraw processing.
- CCXT submit supports one-or-more
signatures when sender and gas owner differ.
- Rewards endpoints include signed points lookups, and auxiliary docs now cover the gas pool service.
Progressive Disclosure
| File | Read when |
|---|
ccxt.md | You need /api/ccxt/* endpoints or stream setup |
native.md | You need /api/perpetuals/* account/market/vault APIs |
auxiliary-endpoints.md | You need builder-codes, gas pool, referrals, rewards, coins, utility txs |
sdk-reference.md | You are coding with SDK classes and methods |
error-handling.md | You are implementing retry, backoff, and failure parsing |
safety-and-risk.md | You are shipping a bot or live strategy safeguards |
gotchas.md | You need a pre-launch pitfalls checklist |
24h Change Check
Use the local helper script to check for OpenAPI changes after the 24h window.
- Script:
skills/api/scripts/check_api_changes.py
- Behavior: if less than 24h since
Last validated, it exits without querying.
- If 24h+ elapsed, it prompts before querying:
Query ... for API changes now? [y/N].
- It never auto-updates skill markdown files; it only records spec hash state in
skills/api/.api-spec-state.json.
Run:
python3 skills/api/scripts/check_api_changes.py
