aptos-dapp-integration

---
name: aptos-dapp-integration
description: Expert on building Aptos dApps with frontend integration. Covers wallet connectivity (Petra, Martian, Pontem), wallet adapter patterns, TypeScript SDK, transaction building and submission, account management, and React/Next.js integration.
allowed-tools: Read, Write, Edit, Grep, Glob, Bash
model: sonnet
license: MIT
metadata:
  author: raintree
  version: "1.0"
---

# Aptos DApp Integration Expert

Expert on integrating Aptos blockchain with frontend applications.

## Triggers

- wallet connect, petra, martian, pontem
- typescript sdk, aptos sdk, @aptos-labs/ts-sdk
- dapp, frontend integration
- wallet adapter, transaction, sign

## Wallet Adapter Setup

### Installation

```bash
npm install @aptos-labs/wallet-adapter-react \
            petra-plugin-wallet-adapter \
            @martianwallet/aptos-wallet-adapter
```

### React Provider

```typescript
import { AptosWalletAdapterProvider } from "@aptos-labs/wallet-adapter-react";
import { PetraWallet } from "petra-plugin-wallet-adapter";
import { MartianWallet } from "@martianwallet/aptos-wallet-adapter";

function App() {
  const wallets = [new PetraWallet(), new MartianWallet()];

  return (
    <AptosWalletAdapterProvider plugins={wallets} autoConnect={true}>
      <YourApp />
    </AptosWalletAdapterProvider>
  );
}
```

### Using Wallet Hooks

```typescript
import { useWallet } from "@aptos-labs/wallet-adapter-react";

function WalletButton() {
  const { connect, disconnect, account, connected, signAndSubmitTransaction } = useWallet();

  if (connected) {
    return (
      <div>
        <p>Connected: {account?.address}</p>
        <button onClick={disconnect}>Disconnect</button>
      </div>
    );
  }

  return <button onClick={() => connect("Petra")}>Connect</button>;
}
```

## TypeScript SDK

### Initialize Client

```typescript
import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";

const config = new AptosConfig({ network: Network.MAINNET });
const aptos = new Aptos(config);
```

### Read Data

```typescript
// Account info
const account = await aptos.getAccountInfo({ accountAddress: "0x..." });

// Resources
const resources = await aptos.getAccountResources({ accountAddress: "0x..." });

// Specific resource
const coin = await aptos.getAccountResource({
  accountAddress: "0x...",
  resourceType: "0x1::coin::CoinStore<0x1::aptos_coin::AptosCoin>"
});

// View function
const result = await aptos.view({
  payload: {
    function: "0x1234::module::get_balance",
    functionArguments: ["0xabcd..."],
  },
});
```

### Submit Transactions

```typescript
const { signAndSubmitTransaction } = useWallet();

const handleTransfer = async () => {
  const response = await signAndSubmitTransaction({
    data: {
      function: "0x1::coin::transfer",
      typeArguments: ["0x1::aptos_coin::AptosCoin"],
      functionArguments: ["0xrecipient...", "100000000"],
    },
  });

  await aptos.waitForTransaction({ transactionHash: response.hash });
};
```

### Transaction with SDK (More Control)

```typescript
// Build
const transaction = await aptos.transaction.build.simple({
  sender: sender.accountAddress,
  data: {
    function: "0x1234::module::my_function",
    functionArguments: [arg1, arg2],
  },
});

// Sign
const senderAuth = aptos.transaction.sign({ signer: sender, transaction });

// Submit
const response = await aptos.transaction.submit.simple({
  transaction,
  senderAuthenticator: senderAuth,
});

// Wait
await aptos.waitForTransaction({ transactionHash: response.hash });
```

## Common Patterns

### Check Balance

```typescript
async function getAptBalance(address: string): Promise<number> {
  const resource = await aptos.getAccountResource({
    accountAddress: address,
    resourceType: "0x1::coin::CoinStore<0x1::aptos_coin::AptosCoin>",
  });
  return Number(resource.coin.value);
}
```

### Display NFTs

```typescript
const nfts = await aptos.getAccountOwnedTokens({ accountAddress: address });
```

### Transaction Status Hook

```typescript
function useTransactionStatus() {
  const [status, setStatus] = useState<"idle" | "pending" | "success" | "error">("idle");

  const submitTransaction = async (txn) => {
    setStatus("pending");
    try {
      const response = await signAndSubmitTransaction(txn);
      await aptos.waitForTransaction({ transactionHash: response.hash });
      setStatus("success");
    } catch {
      setStatus("error");
    }
  };

  return { status, submitTransaction };
}
```

## Error Handling

```typescript
try {
  await signAndSubmitTransaction(txn);
} catch (error: any) {
  if (error.code === 4001) {
    console.error("User rejected");
  } else if (error.message.includes("INSUFFICIENT_BALANCE")) {
    console.error("Insufficient balance");
  }
}
```

## Best Practices

- Always validate input before building transactions
- Show transaction details before signing
- Handle wallet disconnection gracefully
- Check network before submitting
- Use HTTPS for all API calls
- Never ask for private keys