Compare the paths
TypeScript SDK
The TypeScript SDK is Viem-like and supports trading and market making, with the bridge SDK providing transfers to other chains. Like Viem, it runs in web browsers and locally. Use it to integrate Shield Swap into web wallets, trading terminals, and DEX frontends, or into JS/TS agents and backend services. Continue with TypeScript SDK setup, swaps, and liquidity.Python SDK
Use the Python SDK when your service, market making or trading strategy runs in Python. Continue with Python SDK Setup, swaps, and liquidity.Agents
The Shield Swap AgentKit skill links your agent to a guide for account setup and trading. Install it in your agent project:Connect the MCP server
With Node.js 22.13 or later and pnpm 10.33.2, build the AgentKit MCP server and set up a mainnet account:REST API
Use the API when you need market data for a dashboard, service, or trading strategy. It provides indexed reads; you still need a signer and transaction client to submit trades. Start with:- List pools.
- Create an API token for routes and authenticated data.
- Handle pagination and retries.
- Use the generated API reference for exact parameters and responses.
Direct program calls
Use direct program calls when you need to construct transactions below the SDK surface. You take responsibility for record selection, contract-compatible calculations, and recovery when a transaction’s outcome is uncertain.1
Bind the integration to one deployment
Record the network, program ID, edition, checksum, dependency revisions, and storage schema. Do not treat two deployments with the same source name as interchangeable.The current Q128.128 fee-growth layout is incompatible with scalar fee-growth deployments and requires a fresh deployment.
2
Generate complete types and parsers
Mirror nested Leo records and structs, including
u256::U256, MerkleProof, the immutable PositionNFT.withdrawal, and MintComplianceRecord where investigator records are handled.Parse nested structs structurally. Do not split Leo values on commas inside braces. Represent u128 and i128 with arbitrary-precision integers.3
Read the required mappings
Load pool identity, slot state, initialized ticks, positions, pending swap outputs, token settings, and control state required by the task.Version parsers by deployment checksum or release, not by a repository branch name.
4
Mirror amount and swap math exactly
Use native token base units in contract math. Apply display decimals only at the interface boundary. Match fixed-point operations, rounding direction, tick limits, price-limit rules, and iteration caps.Single-hop execution uses five swap iterations. Multi-hop execution uses three iterations per hop. Reaching an initialized tick exactly at the price limit completes the crossing.
5
Own record state
Discover records for the signer, verify token and amount, prevent double selection, preserve change, and mark a record spent only after acceptance is known.Every position change consumes a
PositionNFT. Store the replacement returned by increase, decrease, collect, or rebalance.Rebalance creates a new token ID. Replace the old position identity only after the transaction is accepted.6
Create and retain the confidential address factor
Derive the public confidential address from the exact program address, domain constant, signer, and factor. Persist the factor until claim succeeds and never reuse the resulting address.A deterministic factor derived by a test client is a client convention, not a contract rule.
7
Keep swap and claim in one workflow
After swap acceptance, read
swap_outputs[swap_id] and use its exact stored fields to construct the claim. Persist pending claims across restarts and network failures.8
Verify controls and final state
Read global, token, pair, pool, and position controls before construction. Refresh them before retrying because state can change before finalization.A visible success requires both the expected public mapping change and possession of the expected output records. Test routed calls where
caller != signer.Privacy boundary
In the intended swap flow, your address stays confidential in ordinary public mappings. Trade amounts, routes, pools, output and refund amounts, timing, and market state remain public. Read Protocol boundaries before writing product or privacy claims.Next steps
- Setup configures a mainnet trading account and client.
- Quickstart walks through a swap with test tokens.
- AgentKit’s onboarding guide helps you choose a trading or integration task.