> ## Documentation Index
> Fetch the complete documentation index at: https://docs.actioncodes.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start

> Integrate Action Codes in 5 minutes

This guide gets you from zero to working integration in 5 minutes.

## Prerequisites

* Node.js 18+ (or Bun)
* A user with a Solana wallet
* An auth token (request one by DMing [@beharefe](https://t.me/beharefe) on Telegram or emailing [gm@actioncodes.org](mailto:gm@actioncodes.org))

<Note>
  Users generate codes at [actioncode.app](https://actioncode.app) using their wallet. Your app receives and processes these codes — you don't need wallet access.
</Note>

## Install the SDK

<CodeGroup>
  ```bash npm theme={null}
  npm install @actioncodes/sdk
  ```

  ```bash pnpm theme={null}
  pnpm add @actioncodes/sdk
  ```

  ```bash yarn theme={null}
  yarn add @actioncodes/sdk
  ```

  ```bash bun theme={null}
  bun add @actioncodes/sdk
  ```
</CodeGroup>

## Initialize the client

```typescript theme={null}
import { ActionCodesClient } from '@actioncodes/sdk'

const client = new ActionCodesClient({
  authToken: process.env.ACTION_CODES_TOKEN
})
```

Set your auth token as an environment variable:

```bash theme={null}
export ACTION_CODES_TOKEN="your-auth-token"
```

## Accept a code from a user

When a user wants to interact with your app:

1. They visit [actioncode.app](https://actioncode.app) in their wallet browser
2. They connect their wallet and get an 8-digit code
3. They share that code with your app

```typescript theme={null}
// User provides their code (from actioncode.app)
const code = '48291037'  // example code

// Resolve it to verify and get details
const actionCode = await client.resolve(code)

console.log('Valid code from wallet:', actionCode.pubkey)
console.log('Expires at:', actionCode.expiresAt)
```

## Attach an action

Now attach what you want the user to approve. Choose based on your use case:

<Tabs>
  <Tab title="Sign a Transaction">
    ```typescript theme={null}
    import { Transaction, SystemProgram, PublicKey, Connection } from '@solana/web3.js'

    // Build your transaction
    const connection = new Connection('https://api.mainnet-beta.solana.com')
    const { blockhash } = await connection.getLatestBlockhash()

    const transaction = new Transaction({
      recentBlockhash: blockhash,
      feePayer: new PublicKey(actionCode.pubkey)
    }).add(
      SystemProgram.transfer({
        fromPubkey: new PublicKey(actionCode.pubkey),
        toPubkey: new PublicKey('RecipientAddressHere'),
        lamports: 1_000_000 // 0.001 SOL
      })
    )

    // Serialize and attach to the code
    const serialized = transaction.serialize({
      requireAllSignatures: false
    }).toString('base64')

    await client.attachTransaction(code, serialized)
    ```
  </Tab>

  <Tab title="Sign a Message">
    ```typescript theme={null}
    // Create a message for the user to sign
    const message = 'Sign in to MyApp - ' + new Date().toISOString()

    // Attach it to the code
    await client.attachMessage(code, message)
    ```
  </Tab>
</Tabs>

## Wait for approval

The user will see the pending request in [actioncode.app](https://actioncode.app) and can approve it with their wallet.

```typescript theme={null}
// Watch for the user to approve
for await (const status of client.observeStatus(code)) {
  console.log('Current status:', status.status)

  // Check for transaction signature
  if (status.finalizedSignature) {
    console.log('Transaction signed!')
    console.log('Signature:', status.finalizedSignature)
    break
  }

  // Check for signed message
  if (status.signedMessage) {
    console.log('Message signed!')
    console.log('Signed message:', status.signedMessage)
    break
  }
}
```

## Complete example

Here's everything together — a simple flow where a user signs a message:

```typescript theme={null}
import { ActionCodesClient } from '@actioncodes/sdk'

const client = new ActionCodesClient({
  authToken: process.env.ACTION_CODES_TOKEN
})

async function requestSignature(userCode: string) {
  // 1. Verify the code
  const actionCode = await client.resolve(userCode)
  console.log(`Code valid for wallet: ${actionCode.pubkey}`)

  // 2. Attach a message to sign
  const message = `Verify ownership of ${actionCode.pubkey} at ${Date.now()}`
  await client.attachMessage(userCode, message)
  console.log('Message attached — waiting for user approval...')

  // 3. Wait for signature
  for await (const status of client.observeStatus(userCode)) {
    if (status.signedMessage) {
      console.log('Success! Signed message:', status.signedMessage)
      return status.signedMessage
    }

    // Handle expiry
    if (status.status === 'expired') {
      throw new Error('Code expired before approval')
    }
  }
}

// Usage
const userCode = '48291037' // User provides this from actioncode.app
const signedMessage = await requestSignature(userCode)
```

## User flow summary

<Steps>
  <Step title="User gets a code">
    User opens [actioncode.app](https://actioncode.app) in their wallet browser (Phantom, Solflare, etc.) and taps "Get Code"
  </Step>

  <Step title="User shares the code">
    User copies the 8-digit code and pastes it into your app
  </Step>

  <Step title="Your app attaches an action">
    You call `attachTransaction()` or `attachMessage()`
  </Step>

  <Step title="User approves">
    User sees the request in actioncode.app and taps "Approve" — their wallet signs it
  </Step>

  <Step title="Your app gets the result">
    `observeStatus()` returns the signature or signed message
  </Step>
</Steps>

## Next steps

<CardGroup cols={2}>
  <Card title="How It Works" href="/how-it-works" icon="circle-info">
    Understand the lifecycle in detail
  </Card>

  <Card title="SDK Methods" href="/sdk/methods" icon="code">
    Full API reference
  </Card>

  <Card title="Recipes" href="/recipes/sign-transaction" icon="book">
    Copy-paste examples for common use cases
  </Card>

  <Card title="Playground" href="/playground" icon="play">
    Try it interactively
  </Card>
</CardGroup>