@armory-sh/extensions

Armory x402 SDK — Protocol extensions for x402 payments. Add SIWX, payment ID, Bazaar discovery, and custom extensions.

Documentation | License

Installation

bun add @armory-sh/extensions

Why Armory?

Armory enables HTTP API payments via EIP-3009 transferWithAuthorization. Extensions add powerful functionality like authentication and idempotency.

API Reference

Hook Creators (Client-Side)

import {
  createSIWxHook,
  createPaymentIdHook,
  createCustomHook,

  // Types
  type SIWxHookConfig,
  type PaymentIdHookConfig,
  type CustomHookConfig,
} from '@armory-sh/extensions';

Server Extension Declaration

import {
  // Sign-In-With-X
  declareSIWxExtension,
  createSIWxMessage,
  createSIWxPayload,
  encodeSIWxHeader,
  parseSIWxHeader,
  validateSIWxMessage,
  verifySIWxSignature,
  isSIWxExtension,

  // Payment Identifier
  declarePaymentIdentifierExtension,
  extractPaymentIdentifierInfo,
  isPaymentIdentifierExtension,
  validatePaymentIdentifierExtension,

  // Bazaar Discovery
  declareDiscoveryExtension,
  createDiscoveryConfig,
  extractDiscoveryInfo,
  isDiscoveryExtension,
  validateDiscoveryExtension,

  // Types
  type SIWxExtensionConfig,
  type PaymentIdentifierConfig,
  type BazaarDiscoveryConfig,
  type SIWxPayload,
} from '@armory-sh/extensions';

Extension Utilities

import {
  // Generic Extension
  createExtension,
  extractExtension,
  validateExtension,

  // Payment ID Generation
  generatePaymentId,

  // Constants
  SIGN_IN_WITH_X,
  PAYMENT_IDENTIFIER,
  BAZAAR,

  // Types
  type Extension,
  type SIWxExtensionInfo,
  type PaymentIdentifierExtensionInfo,
  type BazaarExtensionInfo,
} from '@armory-sh/extensions';

Quick Start

Sign-In-With-X (SIWX)

Wallet authentication for repeat access.

import { createSIWxHook } from '@armory-sh/extensions'
import { createX402Client } from '@armory-sh/client-viem'

const client = createX402Client({
  wallet: { type: 'account', account },
  hooks: [
    createSIWxHook({
      domain: 'example.com',
      statement: 'Sign in to access premium content'
    })
  ]
})

Payment Identifier

Idempotency for payment requests.

import { createPaymentIdHook } from '@armory-sh/extensions'

const hook = createPaymentIdHook({ paymentId: 'my-custom-id' })

Custom Hooks

Create your own extensions.

import { createCustomHook } from '@armory-sh/extensions'

const customHook = createCustomHook({
  key: 'my-extension',
  handler: async (context) => {
    if (context.payload) {
      context.payload.extensions = {
        ...(context.payload.extensions ?? {}),
        'my-extension': { data: 'value' }
      }
    }
  },
  priority: 75
})

Server Extension Declaration

For server-side middleware:

import { declareSIWxExtension, declarePaymentIdentifierExtension } from '@armory-sh/extensions'

const siwxExt = declareSIWxExtension({
  domain: 'api.example.com',
  statement: 'Sign in to access this API'
})

const paymentIdExt = declarePaymentIdentifierExtension({ required: true })

Features

• Sign-In-With-X: Wallet authentication for repeat access
• Payment Identifier: Idempotency for payment requests
• Custom Hooks: Create your own extensions
• Server-Side: Declare extensions for middleware

License

MIT © Sawyer Cutler