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

# @atxp/common

> Documentation for the @atxp/common package

## Overview

The [@atxp/common](https://www.npmjs.com/package/@atxp/common) package provides shared utilities, types, and interfaces that are used across all ATXP SDK packages. This package contains the foundational building blocks for authentication, payment processing, and MCP integration.

## Installation

<Info>
  This package is typically installed automatically as a dependency when you install other ATXP packages like `@atxp/client` or `@atxp/express`. You only need to install it directly if you're building custom integrations or extending the ATXP SDK.
</Info>

```bash theme={null}
npm install @atxp/common
```

## Client Types

### Account

The `Account` class represents an ATXP account and handles authentication with the ATXP service.

```typescript theme={null}
import { Account } from '@atxp/common'

const account = new Account(connectionString)
```

<ParamField body="connectionString" type="string" required>
  The ATXP connection string in the format: `https://accounts.atxp.ai?connection_token=<token>`
</ParamField>

**Example usage**

```typescript theme={null}
import { Account } from '@atxp/common'

// Get connection string from environment variables
const connectionString = process.env.ATXP_CONNECTION_STRING
const account = new Account(connectionString)
```

### ClientArgs

Configuration interface for creating ATXP clients.

<Expandable title="ClientArgs properties">
  <ResponseField name="mcpServer" type="string" required>
    The URL of the MCP server to connect to.
  </ResponseField>

  <ResponseField name="account" type="Account" required>
    The ATXP account instance for authentication.
  </ResponseField>

  <ResponseField name="onAuthorize" type="function" optional>
    Callback function called when authorization succeeds.

    ```typescript theme={null}
    onAuthorize: async (data: AuthorizationData) => void
    ```
  </ResponseField>

  <ResponseField name="onAuthorizeFailure" type="function" optional>
    Callback function called when authorization fails.

    ```typescript theme={null}
    onAuthorizeFailure: async (error: AuthorizationError) => void
    ```
  </ResponseField>

  <ResponseField name="onPayment" type="function" optional>
    Callback function called when payment succeeds.

    ```typescript theme={null}
    onPayment: async (data: PaymentData) => void
    ```
  </ResponseField>

  <ResponseField name="onPaymentFailure" type="function" optional>
    Callback function called when payment fails.

    ```typescript theme={null}
    onPaymentFailure: async (error: PaymentError) => void
    ```
  </ResponseField>

  <ResponseField name="approvePayment" type="function" optional>
    Custom payment approval logic.

    ```typescript theme={null}
    approvePayment: async (request: PaymentRequest) => Promise<boolean>
    ```
  </ResponseField>
</Expandable>

### AuthorizationData

Data structure returned when authorization succeeds.

<Expandable title="AuthorizationData properties">
  <ResponseField name="userId" type="string" required>
    Unique identifier for the authorized user.
  </ResponseField>

  <ResponseField name="accessToken" type="string" required>
    OAuth access token for API authentication.
  </ResponseField>

  <ResponseField name="refreshToken" type="string" optional>
    Token used to refresh the access token when it expires.
  </ResponseField>

  <ResponseField name="expiresAt" type="Date" optional>
    Timestamp when the access token expires.
  </ResponseField>
</Expandable>

### PaymentData

Data structure returned when payment succeeds.

<Expandable title="PaymentData properties">
  <ResponseField name="amount" type="BigNumber" required>
    The payment amount in USDC.
  </ResponseField>

  <ResponseField name="currency" type="string" required>
    The payment currency (typically "USDC").
  </ResponseField>

  <ResponseField name="transactionId" type="string" required>
    Unique identifier for the payment transaction.
  </ResponseField>

  <ResponseField name="timestamp" type="Date" required>
    When the payment was processed.
  </ResponseField>

  <ResponseField name="toolName" type="string" optional>
    Name of the tool that triggered the payment.
  </ResponseField>
</Expandable>

### PaymentRequest

Data structure representing a payment request.

<Expandable title="PaymentRequest properties">
  <ResponseField name="amount" type="BigNumber" required>
    The requested payment amount in USDC.
  </ResponseField>

  <ResponseField name="currency" type="string" required>
    The payment currency (typically "USDC").
  </ResponseField>

  <ResponseField name="toolName" type="string" optional>
    Name of the tool requesting payment.
  </ResponseField>

  <ResponseField name="description" type="string" optional>
    Human-readable description of what the payment is for.
  </ResponseField>
</Expandable>

## Error Types

### AuthorizationError

Error thrown when authorization fails.

<Expandable title="AuthorizationError properties">
  <ResponseField name="message" type="string" required>
    Human-readable error message describing the authorization failure.
  </ResponseField>

  <ResponseField name="code" type="string" optional>
    Error code for programmatic error handling.
  </ResponseField>

  <ResponseField name="details" type="object" optional>
    Additional error details and context.
  </ResponseField>
</Expandable>

### PaymentError

Error thrown when payment processing fails.

<Expandable title="PaymentError properties">
  <ResponseField name="message" type="string" required>
    Human-readable error message describing the payment failure.
  </ResponseField>

  <ResponseField name="code" type="string" optional>
    Error code for programmatic error handling.
  </ResponseField>

  <ResponseField name="transactionId" type="string" optional>
    ID of the failed transaction, if available.
  </ResponseField>

  <ResponseField name="details" type="object" optional>
    Additional error details and context.
  </ResponseField>
</Expandable>

## Server Types

### ATXPArgs

Configuration interface for ATXP server middleware.

<Expandable title="ATXPArgs properties">
  <ResponseField name="destination" type="string" required>
    The wallet address where payments will be sent.
  </ResponseField>

  <ResponseField name="payeeName" type="string" optional>
    Human-readable name for the payee, displayed during payment.
  </ResponseField>
</Expandable>