Quick Start

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 on Telegram or emailing gm@actioncodes.org)

Users generate codes at actioncode.app using their wallet. Your app receives and processes these codes — you don’t need wallet access.

Install the SDK

npm install @actioncodes/sdk

pnpm add @actioncodes/sdk

yarn add @actioncodes/sdk

bun add @actioncodes/sdk

Initialize the client

import { ActionCodesClient } from '@actioncodes/sdk'

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

Set your auth token as an environment variable:

export ACTION_CODES_TOKEN="your-auth-token"

Accept a code from a user

When a user wants to interact with your app:

They visit actioncode.app in their wallet browser
They connect their wallet and get an 8-digit code
They share that code with your app

// 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:

Sign a Transaction
Sign a Message

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)

// 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)

Wait for approval

The user will see the pending request in actioncode.app and can approve it with their wallet.

// 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:

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

User gets a code

User opens actioncode.app in their wallet browser (Phantom, Solflare, etc.) and taps “Get Code”

User shares the code

User copies the 8-digit code and pastes it into your app

Your app attaches an action

You call attachTransaction() or attachMessage()

User approves

User sees the request in actioncode.app and taps “Approve” — their wallet signs it

Your app gets the result

observeStatus() returns the signature or signed message

Next steps

How It Works

Understand the lifecycle in detail

SDK Methods

Full API reference

Recipes

Copy-paste examples for common use cases

Playground

Try it interactively

Get Started

SDK Reference

Recipes

Prerequisites

Install the SDK

Initialize the client

Accept a code from a user

Attach an action

Wait for approval

Complete example

User flow summary

Next steps

How It Works

SDK Methods

Recipes

Playground

​Prerequisites

​Install the SDK

​Initialize the client

​Accept a code from a user

​Attach an action

​Wait for approval

​Complete example

​User flow summary

​Next steps

How It Works

SDK Methods

Recipes

Playground

Prerequisites

Install the SDK

Initialize the client

Accept a code from a user

Attach an action

Wait for approval

Complete example

User flow summary

Next steps