Rewrite Application Integration Guide (system-integrators-guide.mdx)
Problem
The current Application Integration Guide is marked deprecated in its own frontmatter and dates back to Oct 2022. BD teams need a reliable page to point partners to when onboarding existing blockchain applications onto Aptos, and this guide should be that page. Right now it can't fill that role because:
- References coins as primary (Aptos is now Fungible Asset first)
- References creation numbers and event handles (no longer current patterns)
- All examples use the Python SDK (TypeScript is the primary supported SDK)
- Transaction submission step is missing from the flow entirely
- 328 lines of coin-centric event tracking with
creation_num / guid / key derivation
- No mention of finality, signing schemes, simulation, orderless transactions, transaction filtering, Geomi, or the Explorer
- The content doesn't flow in a logical order for someone trying to integrate
Meanwhile several major features have shipped since 2022 that integrators need to know about.
Scope from Mar 12 discussion
We discussed what this guide should cover for the target audience (developers who already know blockchain concepts and have built applications on other chains, mostly EVM teams in practice).
Topics identified:
- Finality of the chain
- How to track balances
- How to sign transactions (Ed25519, secp256k1, passkeys)
- How to query historical data and verify it
- Transaction lifecycle: build, encode, sign, submit, check status
- Transaction types (entry functions vs Move scripts)
- BCS encoding (brief, with link out)
- Simulation before submission
- RPC providers (Geomi)
- Asset standards (FA first, coin migration)
Format: skim doc with link-outs, not rabbit holes. Modeled after the Exchange Integration Guide. Tabs for code examples where it makes sense. Flag anything that's missing for follow-up.
AI tools callout: The guide should mention early on that AI coding assistants can help with Aptos integration. Point to the Aptos Agent Skills for Claude Code, Cursor, and Copilot users, and the MCP server for direct API access. There's no application integration skill yet, but Chris is planning to build one. The guide itself can serve as the foundation for what that skill should cover.
Research findings
Audited the current guide against live Aptos state and recent docs (last year of commits, 11 key pages read in detail). Key findings:
AIP-115 Stateless Accounts is live on mainnet. Accounts now implicitly exist with default values (auth_key = address, sequence_number = 0). GET /accounts/{address} never returns 404. Explicit account creation is now optional. This changes the account initialization section significantly.
AIP-123 Orderless Transactions adds a nonce-based alternative to sequence numbers. Enables parallel transaction submission from multiple machines with a 60s max expiration. The guide should present both paths (sequence-based for ordered execution, nonce-based for parallel).
Transaction Filtering (Indexer gRPC v2, added Nov 2025) provides server-side DSL filters for selective transaction processing. This is the modern replacement for the 328-line event-handle parsing approach in the current guide.
Aptos Explorer now shows auto-verified source code on all networks (no Etherscan-style verification needed), supports read/write contract interaction during development, and displays real-time TPS.
Geomi (formerly Aptos Build, build.aptoslabs.com now redirects to geomi.dev) provides RPC, Gas Station, and no-code indexing.
Events are not deprecated. The old key field within events was being replaced by guid, but the events system itself is still the primary tracking mechanism. Transaction Filtering is a newer efficient alternative for production.
TypeScript SDK v6 changes (from reviewing aptos-agent-skills):
aptos.getBalance() is the current way to check balances; getAccountCoinAmount is deprecated. The Exchange Guide still uses the older view function pattern.- Always call
waitForTransaction() after submitting. Submission means the node accepted the transaction, not that it committed.
deploy-object is the modern deployment command, replacing aptos move publish.- Use
bigint for u128/u256 values to avoid JavaScript precision loss.
- The canonical transaction pattern is:
build.simple() then signAndSubmitTransaction() then waitForTransaction().
Smoke tested the outline against a real EVM to Aptos port (Deal-or-Not, 16 Solidity contracts to Move). The aformentioned updates could solve ~70% of integration-layer friction.
Proposed structure
- Overview (what this covers, who it's for)
- Infrastructure & Getting Started (Geomi, full node, indexer, SDKs)
- Accounts & Addresses (AIP-115 stateless accounts, address formats, creation now optional)
- Aptos Explorer (real-time TPS, auto-verified code, read/write contract interaction)
- Asset Standards (FA first, Coin migration, 8 decimals/octas)
- Signing & Transaction Types (signing schemes, BCS vs JSON, entry functions vs scripts)
- Transaction Lifecycle (build, simulate, sign, submit, wait, finality; both sequence-based and orderless paths)
- Retrieving Balances (FA + Coin/migrated, indexer for production)
- Tracking Balance Changes (Transaction Filtering for production, events, gas tracking)
- Historical Data & State (versioning, pruning, REST API + indexer)
- Testing (testnet, faucet, simulation sessions)
Estimated scope
Current guide is 638 lines. Targeting 300 to 400 lines. Maybe couple diagrams. The coin tracking sections compress significantly with the indexer-first approach, but new sections for infrastructure, Explorer, signing, and testing add back some.
Related
Rewrite Application Integration Guide (
system-integrators-guide.mdx)Problem
The current Application Integration Guide is marked deprecated in its own frontmatter and dates back to Oct 2022. BD teams need a reliable page to point partners to when onboarding existing blockchain applications onto Aptos, and this guide should be that page. Right now it can't fill that role because:
creation_num/guid/keyderivationMeanwhile several major features have shipped since 2022 that integrators need to know about.
Scope from Mar 12 discussion
We discussed what this guide should cover for the target audience (developers who already know blockchain concepts and have built applications on other chains, mostly EVM teams in practice).
Topics identified:
Format: skim doc with link-outs, not rabbit holes. Modeled after the Exchange Integration Guide. Tabs for code examples where it makes sense. Flag anything that's missing for follow-up.
AI tools callout: The guide should mention early on that AI coding assistants can help with Aptos integration. Point to the Aptos Agent Skills for Claude Code, Cursor, and Copilot users, and the MCP server for direct API access. There's no application integration skill yet, but Chris is planning to build one. The guide itself can serve as the foundation for what that skill should cover.
Research findings
Audited the current guide against live Aptos state and recent docs (last year of commits, 11 key pages read in detail). Key findings:
AIP-115 Stateless Accounts is live on mainnet. Accounts now implicitly exist with default values (auth_key = address, sequence_number = 0).
GET /accounts/{address}never returns 404. Explicit account creation is now optional. This changes the account initialization section significantly.AIP-123 Orderless Transactions adds a nonce-based alternative to sequence numbers. Enables parallel transaction submission from multiple machines with a 60s max expiration. The guide should present both paths (sequence-based for ordered execution, nonce-based for parallel).
Transaction Filtering (Indexer gRPC v2, added Nov 2025) provides server-side DSL filters for selective transaction processing. This is the modern replacement for the 328-line event-handle parsing approach in the current guide.
Aptos Explorer now shows auto-verified source code on all networks (no Etherscan-style verification needed), supports read/write contract interaction during development, and displays real-time TPS.
Geomi (formerly Aptos Build,
build.aptoslabs.comnow redirects togeomi.dev) provides RPC, Gas Station, and no-code indexing.Events are not deprecated. The old
keyfield within events was being replaced byguid, but the events system itself is still the primary tracking mechanism. Transaction Filtering is a newer efficient alternative for production.TypeScript SDK v6 changes (from reviewing aptos-agent-skills):
aptos.getBalance()is the current way to check balances;getAccountCoinAmountis deprecated. The Exchange Guide still uses the older view function pattern.waitForTransaction()after submitting. Submission means the node accepted the transaction, not that it committed.deploy-objectis the modern deployment command, replacingaptos move publish.bigintfor u128/u256 values to avoid JavaScript precision loss.build.simple()thensignAndSubmitTransaction()thenwaitForTransaction().Smoke tested the outline against a real EVM to Aptos port (Deal-or-Not, 16 Solidity contracts to Move). The aformentioned updates could solve ~70% of integration-layer friction.
Proposed structure
Estimated scope
Current guide is 638 lines. Targeting 300 to 400 lines. Maybe couple diagrams. The coin tracking sections compress significantly with the indexer-first approach, but new sections for infrastructure, Explorer, signing, and testing add back some.
Related