stellar-agent-kit 1.0.0 → 1.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -16,11 +16,6 @@ declare const NetworkConfigSchema: z.ZodObject<{
16
16
  }>;
17
17
  type NetworkConfig = z.infer<typeof NetworkConfigSchema>;
18
18
  declare const networks: {
19
- readonly testnet: {
20
- horizonUrl: string;
21
- sorobanRpcUrl: string;
22
- friendbotUrl?: string | undefined;
23
- };
24
19
  readonly mainnet: {
25
20
  horizonUrl: string;
26
21
  sorobanRpcUrl: string;
@@ -28,7 +23,8 @@ declare const networks: {
28
23
  };
29
24
  };
30
25
  type NetworkName = keyof typeof networks;
31
- declare function getNetworkConfig(name: string): NetworkConfig;
26
+ /** Returns mainnet config. This project is mainnet-only. */
27
+ declare function getNetworkConfig(name?: string): NetworkConfig;
32
28
 
33
29
  /**
34
30
  * DEX / swap types (Stellar: asset = code+issuer or contractId).
@@ -64,12 +60,93 @@ interface DexClient {
64
60
  */
65
61
  declare function createDexClient(networkConfig: NetworkConfig, apiKey?: string): DexClient;
66
62
 
63
+ /**
64
+ * Reflector oracle client – SEP-40 price feeds on Stellar.
65
+ * Uses lastprice(asset) for current price. Asset = Stellar(Address) | Other(Symbol).
66
+ * Contract IDs: https://developers.stellar.org/docs/data/oracles/oracle-providers
67
+ */
68
+
69
+ /** Either a Soroban token contract ID (C...) or a ticker symbol (e.g. "XLM", "BTC") for off-chain feeds. */
70
+ type OracleAsset = {
71
+ contractId: string;
72
+ } | {
73
+ symbol: string;
74
+ };
75
+ interface PriceData {
76
+ price: string;
77
+ timestamp: number;
78
+ decimals: number;
79
+ }
80
+ interface ReflectorOracleConfig {
81
+ networkConfig: NetworkConfig;
82
+ /** Which feed: DEX (default), CEX/DEX, or Fiat. */
83
+ feed?: "dex" | "cexDex" | "fiat";
84
+ }
85
+ declare function createReflectorOracle(config: ReflectorOracleConfig): {
86
+ lastprice: (asset: OracleAsset) => Promise<PriceData>;
87
+ decimals: () => Promise<number>;
88
+ contractId: "CALI2BYU2JE6WVRUFYTS6MSBNEHGJ35P4AVCZYF3B6QOE3QKOB2PLE6M" | "CAFJZQWSED6YAWZU3GWRTOCNPPCGBN32L7QV43XX5LZLFTK6JLN34DLN" | "CBKGPWGKSKZF52CFHMTRR23TBWTPMRDIYZ4O2P5VS65BMHYH4DXMCJZC";
89
+ };
90
+ type ReflectorOracle = ReturnType<typeof createReflectorOracle>;
91
+
92
+ /**
93
+ * Oracle contract addresses (Reflector SEP-40, Band) – mainnet only.
94
+ * Source: https://developers.stellar.org/docs/data/oracles/oracle-providers
95
+ */
96
+ declare const REFLECTOR_ORACLE: {
97
+ /** Stellar Mainnet DEX prices */
98
+ readonly dex: "CALI2BYU2JE6WVRUFYTS6MSBNEHGJ35P4AVCZYF3B6QOE3QKOB2PLE6M";
99
+ /** External CEX & DEX rates */
100
+ readonly cexDex: "CAFJZQWSED6YAWZU3GWRTOCNPPCGBN32L7QV43XX5LZLFTK6JLN34DLN";
101
+ /** Fiat exchange rates */
102
+ readonly fiat: "CBKGPWGKSKZF52CFHMTRR23TBWTPMRDIYZ4O2P5VS65BMHYH4DXMCJZC";
103
+ };
104
+ declare const BAND_ORACLE: "CCQXWMZVM3KRTXTUPTN53YHL272QGKF32L7XEDNZ2S6OSUFK3NFBGG5M";
105
+
106
+ /**
107
+ * Blend lending integration – supply and borrow via Blend Protocol on Stellar.
108
+ * Uses @blend-capital/blend-sdk. Pool IDs: see docs.blend.capital/mainnet-deployments
109
+ */
110
+
111
+ /** Mainnet Blend pool ID. More at mainnet.blend.capital */
112
+ declare const BLEND_POOLS_MAINNET: "CCCCIQSDILITHMM7PBSLVDT5MISSY7R26MNZXCX4H7J5JQ5FPIYOGYFS";
113
+ /** @deprecated Use BLEND_POOLS_MAINNET. Kept for compatibility. */
114
+ declare const BLEND_POOLS: {
115
+ readonly mainnet: "CCCCIQSDILITHMM7PBSLVDT5MISSY7R26MNZXCX4H7J5JQ5FPIYOGYFS";
116
+ };
117
+ interface LendingSupplyArgs {
118
+ /** Pool contract ID (C...). */
119
+ poolId: string;
120
+ /** Reserve asset contract ID (e.g. USDC, XLM token contract). */
121
+ assetContractId: string;
122
+ /** Amount in asset's smallest unit (e.g. 7 decimals for USDC). */
123
+ amount: string;
124
+ }
125
+ interface LendingBorrowArgs {
126
+ poolId: string;
127
+ assetContractId: string;
128
+ amount: string;
129
+ }
130
+ interface LendingResult {
131
+ hash: string;
132
+ status: string;
133
+ }
134
+ /**
135
+ * Supply (deposit) an asset to a Blend pool as collateral or liquidity.
136
+ */
137
+ declare function lendingSupply(networkConfig: NetworkConfig, secretKey: string, args: LendingSupplyArgs): Promise<LendingResult>;
138
+ /**
139
+ * Borrow an asset from a Blend pool.
140
+ */
141
+ declare function lendingBorrow(networkConfig: NetworkConfig, secretKey: string, args: LendingBorrowArgs): Promise<LendingResult>;
142
+
67
143
  /**
68
144
  * StellarAgentKit – unified DeFi agent (MNTAgentKit-style API for Stellar).
69
145
  * Constructor(secretKey, network) + initialize() then protocol methods.
70
146
  */
71
147
 
72
- type StellarNetwork = "mainnet" | "testnet";
148
+ /** This project is mainnet-only. */
149
+ type StellarNetwork = "mainnet";
73
150
  declare class StellarAgentKit {
74
151
  readonly keypair: Keypair;
75
152
  readonly network: StellarNetwork;
@@ -77,7 +154,8 @@ declare class StellarAgentKit {
77
154
  private _initialized;
78
155
  private _dex;
79
156
  private _horizon;
80
- constructor(secretKey: string, network: StellarNetwork);
157
+ private _oracle;
158
+ constructor(secretKey: string, network?: StellarNetwork);
81
159
  /**
82
160
  * Initialize clients (Horizon, Soroban RPC, protocol wrappers).
83
161
  * Call after construction before using protocol methods.
@@ -106,11 +184,23 @@ declare class StellarAgentKit {
106
184
  sendPayment(to: string, amount: string, assetCode?: string, assetIssuer?: string): Promise<{
107
185
  hash: string;
108
186
  }>;
187
+ /**
188
+ * Get latest price for an asset from Reflector oracle.
189
+ * @param asset - { contractId: "C..." } for on-chain token or { symbol: "XLM" } for ticker
190
+ */
191
+ getPrice(asset: OracleAsset): Promise<PriceData>;
192
+ /**
193
+ * Supply (deposit) an asset to a Blend pool.
194
+ */
195
+ lendingSupply(args: LendingSupplyArgs): Promise<LendingResult>;
196
+ /**
197
+ * Borrow an asset from a Blend pool.
198
+ */
199
+ lendingBorrow(args: LendingBorrowArgs): Promise<LendingResult>;
109
200
  }
110
201
 
111
202
  /**
112
- * Stellar asset identifiers and contract addresses.
113
- * Centralized for mainnet/testnet (mirrors Mantle DevKit "Token Addresses").
203
+ * Stellar asset identifiers and contract addresses (mainnet only).
114
204
  */
115
205
  type StellarAsset = {
116
206
  code: string;
@@ -118,19 +208,6 @@ type StellarAsset = {
118
208
  } | {
119
209
  contractId: string;
120
210
  };
121
- declare const TESTNET_ASSETS: {
122
- readonly XLM: {
123
- readonly contractId: "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC";
124
- };
125
- readonly USDC: {
126
- readonly contractId: "CBBHRKEP5M3NUDRISGLJKGHDHX3DA2CN2AZBQY6WLVUJ7VNLGSKBDUCM";
127
- };
128
- /** Classic testnet USDC */
129
- readonly AUSDC: {
130
- readonly code: "AUSDC";
131
- readonly issuer: "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN";
132
- };
133
- };
134
211
  declare const MAINNET_ASSETS: {
135
212
  readonly XLM: {
136
213
  readonly contractId: "CAS3J7GYLGXMF6TDJBBYYSE3HQ6BBSMLNUQ34T6TZMYMW2EVH34XOWMA";
@@ -139,9 +216,7 @@ declare const MAINNET_ASSETS: {
139
216
  readonly contractId: "CCW67TSZV3SSS2HXMBQ5JFGCKJNXKZM7UQUWUZPUTHXSTZLEO7SJMI75";
140
217
  };
141
218
  };
142
- declare const SOROSWAP_AGGREGATOR: {
143
- readonly testnet: "CCJUD55AG6W5HAI5LRVNKAE5WDP5XGZBUDS5WNTIVDU7O264UZZE7BRD";
144
- readonly mainnet: "CAG5LRYQ5JVEUI5TEID72EYOVX44TTUJT5BQR2J6J77FH65PCCFAJDDH";
145
- };
219
+ /** SoroSwap aggregator contract ID (mainnet). */
220
+ declare const SOROSWAP_AGGREGATOR: "CAG5LRYQ5JVEUI5TEID72EYOVX44TTUJT5BQR2J6J77FH65PCCFAJDDH";
146
221
 
147
- export { type DexAsset, type DexClient, MAINNET_ASSETS, type NetworkConfig, type NetworkName, type QuoteResult, SOROSWAP_AGGREGATOR, StellarAgentKit, type StellarAsset, type StellarNetwork, type SwapResult, TESTNET_ASSETS, createDexClient, getNetworkConfig, networks };
222
+ export { BAND_ORACLE, BLEND_POOLS, BLEND_POOLS_MAINNET, type DexAsset, type DexClient, type LendingBorrowArgs, type LendingResult, type LendingSupplyArgs, MAINNET_ASSETS, type NetworkConfig, type NetworkName, type OracleAsset, type PriceData, type QuoteResult, REFLECTOR_ORACLE, type ReflectorOracle, type ReflectorOracleConfig, SOROSWAP_AGGREGATOR, StellarAgentKit, type StellarAsset, type StellarNetwork, type SwapResult, createDexClient, createReflectorOracle, getNetworkConfig, lendingBorrow, lendingSupply, networks };
package/dist/index.d.ts CHANGED
@@ -16,11 +16,6 @@ declare const NetworkConfigSchema: z.ZodObject<{
16
16
  }>;
17
17
  type NetworkConfig = z.infer<typeof NetworkConfigSchema>;
18
18
  declare const networks: {
19
- readonly testnet: {
20
- horizonUrl: string;
21
- sorobanRpcUrl: string;
22
- friendbotUrl?: string | undefined;
23
- };
24
19
  readonly mainnet: {
25
20
  horizonUrl: string;
26
21
  sorobanRpcUrl: string;
@@ -28,7 +23,8 @@ declare const networks: {
28
23
  };
29
24
  };
30
25
  type NetworkName = keyof typeof networks;
31
- declare function getNetworkConfig(name: string): NetworkConfig;
26
+ /** Returns mainnet config. This project is mainnet-only. */
27
+ declare function getNetworkConfig(name?: string): NetworkConfig;
32
28
 
33
29
  /**
34
30
  * DEX / swap types (Stellar: asset = code+issuer or contractId).
@@ -64,12 +60,93 @@ interface DexClient {
64
60
  */
65
61
  declare function createDexClient(networkConfig: NetworkConfig, apiKey?: string): DexClient;
66
62
 
63
+ /**
64
+ * Reflector oracle client – SEP-40 price feeds on Stellar.
65
+ * Uses lastprice(asset) for current price. Asset = Stellar(Address) | Other(Symbol).
66
+ * Contract IDs: https://developers.stellar.org/docs/data/oracles/oracle-providers
67
+ */
68
+
69
+ /** Either a Soroban token contract ID (C...) or a ticker symbol (e.g. "XLM", "BTC") for off-chain feeds. */
70
+ type OracleAsset = {
71
+ contractId: string;
72
+ } | {
73
+ symbol: string;
74
+ };
75
+ interface PriceData {
76
+ price: string;
77
+ timestamp: number;
78
+ decimals: number;
79
+ }
80
+ interface ReflectorOracleConfig {
81
+ networkConfig: NetworkConfig;
82
+ /** Which feed: DEX (default), CEX/DEX, or Fiat. */
83
+ feed?: "dex" | "cexDex" | "fiat";
84
+ }
85
+ declare function createReflectorOracle(config: ReflectorOracleConfig): {
86
+ lastprice: (asset: OracleAsset) => Promise<PriceData>;
87
+ decimals: () => Promise<number>;
88
+ contractId: "CALI2BYU2JE6WVRUFYTS6MSBNEHGJ35P4AVCZYF3B6QOE3QKOB2PLE6M" | "CAFJZQWSED6YAWZU3GWRTOCNPPCGBN32L7QV43XX5LZLFTK6JLN34DLN" | "CBKGPWGKSKZF52CFHMTRR23TBWTPMRDIYZ4O2P5VS65BMHYH4DXMCJZC";
89
+ };
90
+ type ReflectorOracle = ReturnType<typeof createReflectorOracle>;
91
+
92
+ /**
93
+ * Oracle contract addresses (Reflector SEP-40, Band) – mainnet only.
94
+ * Source: https://developers.stellar.org/docs/data/oracles/oracle-providers
95
+ */
96
+ declare const REFLECTOR_ORACLE: {
97
+ /** Stellar Mainnet DEX prices */
98
+ readonly dex: "CALI2BYU2JE6WVRUFYTS6MSBNEHGJ35P4AVCZYF3B6QOE3QKOB2PLE6M";
99
+ /** External CEX & DEX rates */
100
+ readonly cexDex: "CAFJZQWSED6YAWZU3GWRTOCNPPCGBN32L7QV43XX5LZLFTK6JLN34DLN";
101
+ /** Fiat exchange rates */
102
+ readonly fiat: "CBKGPWGKSKZF52CFHMTRR23TBWTPMRDIYZ4O2P5VS65BMHYH4DXMCJZC";
103
+ };
104
+ declare const BAND_ORACLE: "CCQXWMZVM3KRTXTUPTN53YHL272QGKF32L7XEDNZ2S6OSUFK3NFBGG5M";
105
+
106
+ /**
107
+ * Blend lending integration – supply and borrow via Blend Protocol on Stellar.
108
+ * Uses @blend-capital/blend-sdk. Pool IDs: see docs.blend.capital/mainnet-deployments
109
+ */
110
+
111
+ /** Mainnet Blend pool ID. More at mainnet.blend.capital */
112
+ declare const BLEND_POOLS_MAINNET: "CCCCIQSDILITHMM7PBSLVDT5MISSY7R26MNZXCX4H7J5JQ5FPIYOGYFS";
113
+ /** @deprecated Use BLEND_POOLS_MAINNET. Kept for compatibility. */
114
+ declare const BLEND_POOLS: {
115
+ readonly mainnet: "CCCCIQSDILITHMM7PBSLVDT5MISSY7R26MNZXCX4H7J5JQ5FPIYOGYFS";
116
+ };
117
+ interface LendingSupplyArgs {
118
+ /** Pool contract ID (C...). */
119
+ poolId: string;
120
+ /** Reserve asset contract ID (e.g. USDC, XLM token contract). */
121
+ assetContractId: string;
122
+ /** Amount in asset's smallest unit (e.g. 7 decimals for USDC). */
123
+ amount: string;
124
+ }
125
+ interface LendingBorrowArgs {
126
+ poolId: string;
127
+ assetContractId: string;
128
+ amount: string;
129
+ }
130
+ interface LendingResult {
131
+ hash: string;
132
+ status: string;
133
+ }
134
+ /**
135
+ * Supply (deposit) an asset to a Blend pool as collateral or liquidity.
136
+ */
137
+ declare function lendingSupply(networkConfig: NetworkConfig, secretKey: string, args: LendingSupplyArgs): Promise<LendingResult>;
138
+ /**
139
+ * Borrow an asset from a Blend pool.
140
+ */
141
+ declare function lendingBorrow(networkConfig: NetworkConfig, secretKey: string, args: LendingBorrowArgs): Promise<LendingResult>;
142
+
67
143
  /**
68
144
  * StellarAgentKit – unified DeFi agent (MNTAgentKit-style API for Stellar).
69
145
  * Constructor(secretKey, network) + initialize() then protocol methods.
70
146
  */
71
147
 
72
- type StellarNetwork = "mainnet" | "testnet";
148
+ /** This project is mainnet-only. */
149
+ type StellarNetwork = "mainnet";
73
150
  declare class StellarAgentKit {
74
151
  readonly keypair: Keypair;
75
152
  readonly network: StellarNetwork;
@@ -77,7 +154,8 @@ declare class StellarAgentKit {
77
154
  private _initialized;
78
155
  private _dex;
79
156
  private _horizon;
80
- constructor(secretKey: string, network: StellarNetwork);
157
+ private _oracle;
158
+ constructor(secretKey: string, network?: StellarNetwork);
81
159
  /**
82
160
  * Initialize clients (Horizon, Soroban RPC, protocol wrappers).
83
161
  * Call after construction before using protocol methods.
@@ -106,11 +184,23 @@ declare class StellarAgentKit {
106
184
  sendPayment(to: string, amount: string, assetCode?: string, assetIssuer?: string): Promise<{
107
185
  hash: string;
108
186
  }>;
187
+ /**
188
+ * Get latest price for an asset from Reflector oracle.
189
+ * @param asset - { contractId: "C..." } for on-chain token or { symbol: "XLM" } for ticker
190
+ */
191
+ getPrice(asset: OracleAsset): Promise<PriceData>;
192
+ /**
193
+ * Supply (deposit) an asset to a Blend pool.
194
+ */
195
+ lendingSupply(args: LendingSupplyArgs): Promise<LendingResult>;
196
+ /**
197
+ * Borrow an asset from a Blend pool.
198
+ */
199
+ lendingBorrow(args: LendingBorrowArgs): Promise<LendingResult>;
109
200
  }
110
201
 
111
202
  /**
112
- * Stellar asset identifiers and contract addresses.
113
- * Centralized for mainnet/testnet (mirrors Mantle DevKit "Token Addresses").
203
+ * Stellar asset identifiers and contract addresses (mainnet only).
114
204
  */
115
205
  type StellarAsset = {
116
206
  code: string;
@@ -118,19 +208,6 @@ type StellarAsset = {
118
208
  } | {
119
209
  contractId: string;
120
210
  };
121
- declare const TESTNET_ASSETS: {
122
- readonly XLM: {
123
- readonly contractId: "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC";
124
- };
125
- readonly USDC: {
126
- readonly contractId: "CBBHRKEP5M3NUDRISGLJKGHDHX3DA2CN2AZBQY6WLVUJ7VNLGSKBDUCM";
127
- };
128
- /** Classic testnet USDC */
129
- readonly AUSDC: {
130
- readonly code: "AUSDC";
131
- readonly issuer: "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN";
132
- };
133
- };
134
211
  declare const MAINNET_ASSETS: {
135
212
  readonly XLM: {
136
213
  readonly contractId: "CAS3J7GYLGXMF6TDJBBYYSE3HQ6BBSMLNUQ34T6TZMYMW2EVH34XOWMA";
@@ -139,9 +216,7 @@ declare const MAINNET_ASSETS: {
139
216
  readonly contractId: "CCW67TSZV3SSS2HXMBQ5JFGCKJNXKZM7UQUWUZPUTHXSTZLEO7SJMI75";
140
217
  };
141
218
  };
142
- declare const SOROSWAP_AGGREGATOR: {
143
- readonly testnet: "CCJUD55AG6W5HAI5LRVNKAE5WDP5XGZBUDS5WNTIVDU7O264UZZE7BRD";
144
- readonly mainnet: "CAG5LRYQ5JVEUI5TEID72EYOVX44TTUJT5BQR2J6J77FH65PCCFAJDDH";
145
- };
219
+ /** SoroSwap aggregator contract ID (mainnet). */
220
+ declare const SOROSWAP_AGGREGATOR: "CAG5LRYQ5JVEUI5TEID72EYOVX44TTUJT5BQR2J6J77FH65PCCFAJDDH";
146
221
 
147
- export { type DexAsset, type DexClient, MAINNET_ASSETS, type NetworkConfig, type NetworkName, type QuoteResult, SOROSWAP_AGGREGATOR, StellarAgentKit, type StellarAsset, type StellarNetwork, type SwapResult, TESTNET_ASSETS, createDexClient, getNetworkConfig, networks };
222
+ export { BAND_ORACLE, BLEND_POOLS, BLEND_POOLS_MAINNET, type DexAsset, type DexClient, type LendingBorrowArgs, type LendingResult, type LendingSupplyArgs, MAINNET_ASSETS, type NetworkConfig, type NetworkName, type OracleAsset, type PriceData, type QuoteResult, REFLECTOR_ORACLE, type ReflectorOracle, type ReflectorOracleConfig, SOROSWAP_AGGREGATOR, StellarAgentKit, type StellarAsset, type StellarNetwork, type SwapResult, createDexClient, createReflectorOracle, getNetworkConfig, lendingBorrow, lendingSupply, networks };