@atxp/common

Overview

The @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

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.

npm install @atxp/common

Client Types

Account

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

import { Account } from '@atxp/common'

const account = new Account(connectionString)

connectionString

string

required

The ATXP connection string in the format: https://accounts.atxp.ai?connection_token=<token>

Example usage

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.

Show ClientArgs properties

mcpServer

string

required

The URL of the MCP server to connect to.

account

Account

required

The ATXP account instance for authentication.

onAuthorize

function

Callback function called when authorization succeeds.

onAuthorize: async (data: AuthorizationData) => void

onAuthorizeFailure

function

Callback function called when authorization fails.

onAuthorizeFailure: async (error: AuthorizationError) => void

onPayment

function

Callback function called when payment succeeds.

onPayment: async (data: PaymentData) => void

onPaymentFailure

function

Callback function called when payment fails.

onPaymentFailure: async (error: PaymentError) => void

approvePayment

function

Custom payment approval logic.

approvePayment: async (request: PaymentRequest) => Promise<boolean>

AuthorizationData

Data structure returned when authorization succeeds.

Show AuthorizationData properties

userId

string

required

Unique identifier for the authorized user.

accessToken

string

required

OAuth access token for API authentication.

refreshToken

string

Token used to refresh the access token when it expires.

expiresAt

Date

Timestamp when the access token expires.

PaymentData

Data structure returned when payment succeeds.

Show PaymentData properties

amount

BigNumber

required

The payment amount in USDC.

currency

string

required

The payment currency (typically “USDC”).

transactionId

string

required

Unique identifier for the payment transaction.

timestamp

Date

required

When the payment was processed.

toolName

string

Name of the tool that triggered the payment.

PaymentRequest

Data structure representing a payment request.

Show PaymentRequest properties

amount

BigNumber

required

The requested payment amount in USDC.

currency

string

required

The payment currency (typically “USDC”).

toolName

string

Name of the tool requesting payment.

description

string

Human-readable description of what the payment is for.

Error Types

AuthorizationError

Error thrown when authorization fails.

Show AuthorizationError properties

message

string

required

Human-readable error message describing the authorization failure.

code

string

Error code for programmatic error handling.

details

object

Additional error details and context.

PaymentError

Error thrown when payment processing fails.

Show PaymentError properties

message

string

required

Human-readable error message describing the payment failure.

code

string

Error code for programmatic error handling.

transactionId

string

ID of the failed transaction, if available.

details

object

Additional error details and context.

Server Types

ATXPArgs

Configuration interface for ATXP server middleware.

Show ATXPArgs properties

destination

string

required

The wallet address where payments will be sent.

payeeName

string

Human-readable name for the payee, displayed during payment.

Overview

Build Agents

Monetize MCP Tools

Developer Tools

API Reference

Overview

Installation

Client Types

Account

ClientArgs

AuthorizationData

PaymentData

PaymentRequest

Error Types

AuthorizationError

PaymentError

Server Types

ATXPArgs

​Overview

​Installation

​Client Types

​Account

​ClientArgs

​AuthorizationData

​PaymentData

​PaymentRequest

​Error Types

​AuthorizationError

​PaymentError

​Server Types

​ATXPArgs

Overview

Installation

Client Types

Account

ClientArgs

AuthorizationData

PaymentData

PaymentRequest

Error Types

AuthorizationError

PaymentError

Server Types

ATXPArgs