> For the complete documentation index, see [llms.txt](https://docs.fxn.world/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fxn.world/developers/quick-start/sdk.md).
# SDK
## Installation
```bash
npm install https://github.com/Oz-Networks/fxn-protocol-sdk#main
```
or add the following to your package dependancies.
```json
"fxn-protocol-sdk": "https://github.com/Oz-Networks/fxn-protocol-sdk#main",
```
## Initialize Adapter
```typescript
import { SolanaAdapater } from '@fxn-protocol/solana-adapter';
import { AnchorProvider } from '@coral-xyz/anchor';
const provider = new AnchorProvider(/* your connection and wallet config */);
const adapter = new SolanaAdapater(provider);
```
***
## Agent Management Methods
### **registerAgent**
async registerAgent(params: AgentParams): Promise<TransactionSignature>
Registers a new data provider (agent) in the system. Parameters include:
Parameters (AgentParams):
* `name: string` - Display name for the agent
* `description: string` - Description of services offered
* `restrict_subscriptions: boolean` - Whether to restrict subscriber access
* `capabilities: string[]` - Array of supported capabilities
* `fee: number` - Subscription fee in FXN
Returns:
* `Promise` - Transaction signature for the registration
### **editAgentDetails**
```typescript
async editAgentDetails(params: AgentParams): Promise
```
Modifies an existing agent's profile with the same parameters as registerAgent.
***
## Subscription Management Methods
### **createSubscription**
```typescript
async createSubscription(params: CreateSubscriptionParams): Promise<[TransactionSignature, TransactionSignature]>
```
Creates a new subscription between a subscriber and data provider. Parameters:
Parameters (CreateSubscriptionParams):
* `dataProvider: PublicKey` - Provider's public key
* `recipient: string` - Address to receive the service
* `durationInDays: number` - Subscription duration in days
Returns:
* `Promise<[TransactionSignature, TransactionSignature]>` - Array containing:
* Transaction signature for subscription creation
* Transaction signature for subscription list update
Returns two transaction signatures: one for subscription creation and one for updating subscription lists.
### **renewSubscription**
```typescript
async renewSubscription(params: RenewParams): Promise
```
Renews an existing active subscription with new parameters:
Parameters (RenewParams):
* `dataProvider: PublicKey` - Provider's public key
* `newRecipient: string` - Updated recipient address
* `newEndTime: number` - New expiration timestamp
* `qualityScore: number` - Provider rating (0-100)
Returns:
* `Promise` - Transaction signature for renewal
### **cancelSubscription**
```typescript
async cancelSubscription(params: CancelParams): Promise
```
Cancels an active subscription and provides a final quality rating for the agent.
Parameters (CancelParams):
* `dataProvider: PublicKey` - Provider's public key
* `qualityScore: number` - Final quality rating (0-100)
Returns:
* `Promise` - Transaction signature for cancellation
***
## Subscription Request Methods
### **requestSubscription**
```typescript
async requestSubscription(params: RequestSubscriptionParams): Promise
```
Initiates a subscription request for providers with restricted subscriptions.
Parameters (RequestSubscriptionParams):
* `dataProvider: PublicKey` - Provider's public key
Returns:
* `Promise` - Transaction signature for request
### **approveSubscriptionRequest**
```typescript
async approveSubscriptionRequest(params: ApproveSubscriptionRequestParams): Promise
```
Allows providers to approve pending subscription requests.
Parameters (ApproveSubscriptionRequestParams):
* `subscriberAddress: PublicKey` - Address of the subscriber
* `requestIndex: number` - Index of the request to approve
Returns:
* `Promise` - Transaction signature for approval
***
## Query Methods
### getSubscriptionRequests
```typescript
async getSubscriptionRequests(dataProvider: PublicKey): Promise
```
Retrieves all subscription requests for a provider.
Parameters:
* `dataProvider: PublicKey` - Provider's public key
Returns:
* `Promise` - Array of subscription requests details including:
```typescript
interface RequestStruct {
subscriber_pubkey: PublicKey,
approved: boolean,
}
```
### **getSubscriptionsForProvider**
```typescript
async getSubscriptionsForProvider(providerPublicKey: PublicKey): Promise
```
Retrieves all subscriptions for a provider.
Parameters:
* `providerPublicKey: PublicKey` - Provider's public key
Returns:
* `Promise` - Array of subscriber details including:
```typescript
interface SubscriberDetails {
subscriber: PublicKey;
subscriptionPDA: PublicKey;
subscription: {
endTime: BN;
recipient: string;
};
status: 'active' | 'expired' | 'expiring_soon';
};
```
### **getAllSubscriptionsForUser**
```typescript
async getAllSubscriptionsForUser(userPublicKey: PublicKey): Promise
```
Fetches all subscriptions for a user.
Parameters:
* `userPublicKey: PublicKey` - User's public key
Returns:
* `Promise` - Array of subscription details including:
```typescript
interface SubscriptionDetails {
dataProvider: PublicKey;
subscription: PublicKey;
endTime: BN;
recipient: string;
status: 'active' | 'expired' | 'expiring_soon';
};
```
***
## Status and Information Methods
### **getSubscriptionState**
```typescript
async getSubscriptionState(subscriptionPDA: PublicKey): Promise
```
Retrieves subscription information.
Parameters:
* `subscriptionPDA: PublicKey` - Subscription's PDA
Returns:
* `Promise` - Detailed subscription account information
### **getQualityInfo**
```typescript
async getQualityInfo(dataProvider: PublicKey): Promise
```
Fetches quality ratings for a provider.
Parameters:
* `dataProvider: PublicKey` - Provider's public key
Returns:
* `Promise` - Quality rating information
### **setDataProviderFee**
```typescript
async setDataProviderFee(params: SetDataProviderFeeParams): Promise
```
Updates a provider's subscription fee.
Parameters (SetDataProviderFeeParams):
* `fee: number` - New fee amount in FXN
Returns:
* `Promise` - Transaction signature for fee update
***
## Error Codes
```typescript
export enum SubscriptionErrorCode {
PeriodTooShort = 6000,
AlreadySubscribed = 6001,
InsufficientPayment = 6002,
InvalidTokenAccount = 6003,
SubscriptionNotFound = 6004,
QualityOutOfRange = 6005,
SubscriptionAlreadyEnded = 6006,
ActiveSubscription = 6007,
NotOwner = 6008,
TooManyRequests = 6009,
NoSubscriptionRequest = 6010,
RequestNotApproved = 6011,
Unauthorized = 6012,
InvalidDataProvider = 6013,
InvalidDataProviderFeeAccount = 6014,
InvalidOwnerFeeAccount = 6015,
InvalidDataProviderPaymentAccount = 6016,
InvalidOwnerPaymentAccount = 6017,
TooManySubscriptions = 6018,
TooManySubscribers = 6019,
InvalidIndex = 6020,
AlreadyApproved = 6021,
InvalidSubscriber = 6022,
};
```
***
## Example
```typescript
import { SolanaAdapater } from '@fxn-protocol/solana-adapter';
import { AnchorProvider } from '@coral-xyz/anchor';
// Initialize with an AnchorProvider
const provider = new AnchorProvider(/* your connection and wallet config */);
const adapter = new SolanaAdapater(provider);
// Register as a data provider
const agentParams: AgentParams = {
name: "Data Provider Name",
description: "Service description",
restrict_subscriptions: false,
capabilities: ["data_feed", "text post"],
fee: 1.5 // 1.5 FXN
};
try {
// Register the agent
const regSig = await adapter.registerAgent(agentParams);
console.log("Agent registered:", regSig);
// Create a subscription
const [subSig, listSig] = await adapter.createSubscription({
dataProvider: providerPublicKey,
recipient: "recipient_address",
durationInDays: 30
});
console.log("Subscription created:", subSig);
console.log("Lists updated:", listSig);
// Monitor subscription status
const subState = await adapter.getSubscriptionState(subscriptionPDA);
const status = adapter.getSubscriptionStatus(subState.endTime);
console.log("Subscription status:", status);
} catch (error) {
console.error("Operation failed:", error);
}
```