@autonomys/auto-drive 1.6.8 → 1.6.10

package/README.md

@@ -312,6 +312,108 @@ try {
 }
 ```
 
+### Pay with AI3 — purchasing storage credits
+
+Storage on the Autonomys Network is paid for with AI3 tokens via an on-chain payment intent flow. The SDK handles all of the Auto Drive API interactions; you supply the on-chain transaction using your preferred EVM wallet library (wagmi, viem, ethers, etc.).
+
+#### The flow
+
+```
+0. getStoragePrice(api)                  → optional: show live price estimate before payment
+1. createPaymentIntent(api, sizeBytes)   → locks price, returns amount + contract details
+2. send ai3AmountWei to contractAddress  → payIntent(intentId) on-chain (your wallet code)
+3. watchPaymentTransaction(api, id, tx)  → notifies Auto Drive of your tx hash
+4. waitForPaymentCompletion(api, id)     → polls until COMPLETED (credits applied)
+```
+
+#### Important: keep your API key server-side
+
+`createPaymentIntent`, `watchPaymentTransaction`, and `getPaymentIntentStatus` all require an API key. In a web application these calls must be made from your server (e.g. a Next.js API route, an Express handler), not from the browser. `getStoragePrice` and `getPaymentContractInfo` are public endpoints and can be called from anywhere.
+
+#### Getting a live price estimate
+
+```typescript
+// Public endpoint — no API key required. Good for showing a cost estimate
+// before the user connects a wallet or commits to a payment.
+const publicApi = createAutoDriveApi({ apiKey: null, network: NetworkId.MAINNET })
+const { shannonsPerByte, ai3PerGb } = await publicApi.getStoragePrice()
+
+console.log(`Current price: ${ai3PerGb} AI3/GB`)
+```
+
+#### Server-side example (Node / Next.js API route)
+
+```typescript
+import { createAutoDriveApi } from '@autonomys/auto-drive'
+import { NetworkId } from '@autonomys/auto-utils'
+
+// Run on your server — never expose your API key to the browser
+const api = createAutoDriveApi({ apiKey: process.env.AUTO_DRIVE_API_KEY!, network: NetworkId.MAINNET })
+
+// Step 1 — create a price-locked intent for the content you want to store
+const intent = await api.createPaymentIntent(contentSizeBytes)
+// intent.ai3AmountWei  — exact amount to send (as a BigInt-safe string)
+// intent.ai3Amount     — human-readable amount, e.g. "0.00123"
+// intent.contractAddress — Credits Receiver contract on Auto EVM
+// intent.intentId      — pass as the bytes32 arg to payIntent()
+// intent.expiresAt     — ISO timestamp, intent expires after 10 minutes
+
+// Step 2 — your client sends the on-chain transaction (see below)
+// const txHash = await walletClient.writeContract({ ... })
+
+// Step 3 — submit the tx hash so Auto Drive can watch it
+await api.watchPaymentTransaction(intent.intentId, txHash)
+
+// Step 4 — poll until credits are applied (or intent expires/fails)
+const result = await api.waitForPaymentCompletion(intent.intentId)
+// result: 'COMPLETED' | 'EXPIRED' | 'FAILED' | 'OVER_CAP'
+
+if (result === 'COMPLETED') {
+  console.log('Credits applied — ready to upload')
+}
+```
+
+#### Client-side example (browser, using viem)
+
+```typescript
+import { createAutoDriveApi } from '@autonomys/auto-drive'
+import { NetworkId } from '@autonomys/auto-utils'
+import { createWalletClient, custom, parseGwei } from 'viem'
+
+// Step 1 — fetch contract details (public endpoint, no API key needed)
+const publicApi = createAutoDriveApi({ apiKey: null, network: NetworkId.MAINNET })
+const contractInfo = await publicApi.getPaymentContractInfo()
+
+// Step 2 — send the on-chain transaction with your wallet
+const walletClient = createWalletClient({ transport: custom(window.ethereum) })
+const [account] = await walletClient.requestAddresses()
+
+const txHash = await walletClient.writeContract({
+  address: contractInfo.contractAddress as `0x${string}`,
+  abi: contractInfo.payIntentAbi,
+  functionName: 'payIntent',
+  args: [intent.intentId as `0x${string}`],
+  value: BigInt(intent.ai3AmountWei),
+})
+// Then call your server route to run steps 3 and 4
+```
+
+#### Polling with custom options
+
+```typescript
+const result = await api.waitForPaymentCompletion(intent.intentId, {
+  pollIntervalMs: 5_000,  // check every 5 seconds (default: 3 000)
+  timeoutMs: 120_000,     // give up after 2 minutes (default: 300 000)
+})
+```
+
+#### Checking intent status manually
+
+```typescript
+const { id, status } = await api.getPaymentIntentStatus(intent.intentId)
+// status: 'PENDING' | 'CONFIRMED' | 'COMPLETED' | 'EXPIRED' | 'FAILED' | 'OVER_CAP'
+```
+
 ## License
 
 This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

package/dist/api/calls/index.d.ts

@@ -73,6 +73,15 @@ export declare const apiCalls: {
     }>) => Promise<import("..").ObjectInformation["metadata"]>;
     getMe: (api: import("..").AutoDriveApiHandler) => Promise<import("../models/user").UserInfo>;
     getToBeReviewedList: (api: import("..").AutoDriveApiHandler, query: import("../../utils").ArgsWithPagination) => Promise<import("..").ObjectSummary[]>;
+    getStoragePrice: (api: import("..").AutoDriveApiHandler) => Promise<import("..").StoragePrice>;
+    getPaymentContractInfo: (api: import("..").AutoDriveApiHandler) => Promise<import("..").PaymentContractInfo>;
+    createPaymentIntent: (api: import("..").AutoDriveApiHandler, sizeBytes: number) => Promise<import("..").PaymentIntent>;
+    watchPaymentTransaction: (api: import("..").AutoDriveApiHandler, intentId: string, txHash: string) => Promise<void>;
+    getPaymentIntentStatus: (api: import("..").AutoDriveApiHandler, intentId: string) => Promise<{
+        id: string;
+        status: import("..").PaymentIntentStatus;
+    }>;
+    waitForPaymentCompletion: (api: import("..").AutoDriveApiHandler, intentId: string, { pollIntervalMs, timeoutMs }?: import("..").PollOptions) => Promise<import("..").PaymentIntentTerminalStatus>;
     downloadObject: (api: import("..").AutoDriveApiHandler, query: import("../../utils").ArgsWithoutPagination<{
         cid: string;
         ignoreBackendEncoding?: boolean;
@@ -86,4 +95,5 @@ export declare const apiCalls: {
         status: import("../models/asyncDownloads").DownloadStatus;
     }>;
 };
+export { getStoragePrice, getPaymentContractInfo, createPaymentIntent, watchPaymentTransaction, getPaymentIntentStatus, waitForPaymentCompletion, } from './payment';
 //# sourceMappingURL=index.d.ts.map

package/dist/api/calls/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/api/calls/index.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,QAAQ;kBAMshB,qCAA2B,EAAC;;;MAAkE;0BAAqiC,qCAA2B,EAAC;;MAAgD;oBAAo7B,qCAA2B,EAAC;;MAAgD;oBAAy6B,qCAA2B,EAAC;;MAAgD;;;mBAAq3B,qCAA2B,EAAC;;MAAgD;gBAAuzB,qCAA2B,EAAC;;MAAgD;oBAAy3B,qCAA2B,EAAC;;MAAgD;uBAAjxL,qCAA2B,EAAC;gBAAkG,CAAC;;;MAA8E;yBAA4iC,qCAA2B,EAAC;;qBAA2G,CAAC;MAAsB;yCAA+1C,qCAA2B,EAAC;;;gBAAkK,CAAC;;;MAAyE;sBAAm1C,qCAA2B,EAAC;;;;MAAuH;qBAA6qC,qCAA2B,EAAC;;MAA4D;eAAz7L,qCAA2B,EAAC;;MAA8C;sBAA89B,qCAA2B,EAAC,+CAA4B;wBAA0X,qCAA2B,EAAC;;;MAAgE;iBAAg8B,qCAA2B,EAAC,+CAA4B;gBAA88B,qCAA2B,EAAC;;MAAgD;uBAAo1B,qCAA2B,EAAC;;MAAgD;4BAAi+B,qCAA2B,EAAC;;MAAgD;sBAAq+B,qCAA2B,EAAC;;MAAgD;wBAAggC,qCAA2B,EAAC;;MAAgD;YAA+jB,qCAAwB;0BAA4yB,qCAA2B,EAAC,+CAA4B;qBAJzlT,qCAEP,EAAC;;6BAEiD,CAAC;MAAY;0BAAohB,qCAA2B,EAAC,WAAc;uBAAgV,qCAA2B,EAAC,kBAAqB;wBAAoV,qCAAwB;2BAAgV,qCAA2B,EAAC,kBAAqB;wBAA6R,qCAAwB,EAAC,WAAY;qBAA+G,qCAA2B,EAAC,WAAc;;;CADzsE,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/api/calls/index.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,QAAQ;kBAkByJ,qCAA2B,EAAC;;;MAAkE;0BAAqiC,qCAA2B,EAAC;;MAAgD;oBAAo7B,qCAA2B,EAAC;;MAAgD;oBAAy6B,qCAA2B,EAAC;;MAAgD;;;mBAAq3B,qCAA2B,EAAC;;MAAgD;gBAAuzB,qCAA2B,EAAC;;MAAgD;oBAAy3B,qCAA2B,EAAC;;MAAgD;uBAAjxL,qCAA2B,EAAC;gBAAkG,CAAC;;;MAA8E;yBAA4iC,qCAA2B,EAAC;;qBAA2G,CAAC;MAAsB;yCAA+1C,qCAA2B,EAAC;;;gBAAkK,CAAC;;;MAAyE;sBAAm1C,qCAA2B,EAAC;;;;MAAuH;qBAA6qC,qCAA2B,EAAC;;MAA4D;eAAz7L,qCAA2B,EAAC;;MAA8C;sBAA89B,qCAA2B,EAAC,+CAA4B;wBAA0X,qCAA2B,EAAC;;;MAAgE;iBAAg8B,qCAA2B,EAAC,+CAA4B;gBAA88B,qCAA2B,EAAC;;MAAgD;uBAAo1B,qCAA2B,EAAC;;MAAgD;4BAAi+B,qCAA2B,EAAC;;MAAgD;sBAAq+B,qCAA2B,EAAC;;MAAgD;wBAAggC,qCAA2B,EAAC;;MAAgD;YAA+jB,qCAAwB;0BAA4yB,qCAA2B,EAAC,+CAA4B;sBAAlmS,qCAAwB;6BAAooB,qCAA2B;0BAAgwC,qCAA2B,EAAC,iBAAoB;8BAAshC,qCAA2B,EAAC,gBAAmB,EAAC,cAAiB;6BAA6kB,qCAA2B,EAAC,gBAAmB;;;;+BAAy5B,qCAA2B,EAAC,gBAAmB,EAAC,wDAAoE;qBAlB7zJ,qCACC,EAAC;;6BAIL,CAAC;MAGR;0BAUqN,qCAA2B,EAAC,WAAc;uBAAgV,qCAA2B,EAAC,kBAAqB;wBAAoV,qCAAwB;2BAAgV,qCAA2B,EAAC,kBAAqB;wBAA6R,qCAAwB,EAAC,WAAY;qBAA+G,qCAA2B,EAAC,WAAc;;;CAZ50D,CAAA;AAID,OAAO,EACL,eAAe,EACf,sBAAsB,EACtB,mBAAmB,EACnB,uBAAuB,EACvB,sBAAsB,EACtB,wBAAwB,GACzB,MAAM,WAAW,CAAA"}

package/dist/api/calls/index.js

@@ -33,9 +33,19 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.apiCalls = void 0;
+exports.waitForPaymentCompletion = exports.getPaymentIntentStatus = exports.watchPaymentTransaction = exports.createPaymentIntent = exports.getPaymentContractInfo = exports.getStoragePrice = exports.apiCalls = void 0;
 const downloadCalls = __importStar(require("./download"));
+const paymentCalls = __importStar(require("./payment"));
 const readCalls = __importStar(require("./read"));
 const uploadCalls = __importStar(require("./upload"));
 const writeCalls = __importStar(require("./write"));
-exports.apiCalls = Object.assign(Object.assign(Object.assign(Object.assign({}, downloadCalls), readCalls), uploadCalls), writeCalls);
+exports.apiCalls = Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({}, downloadCalls), paymentCalls), readCalls), uploadCalls), writeCalls);
+// Re-export payment utilities as named exports so callers can use them
+// as standalone functions without going through the apiCalls object.
+var payment_1 = require("./payment");
+Object.defineProperty(exports, "getStoragePrice", { enumerable: true, get: function () { return payment_1.getStoragePrice; } });
+Object.defineProperty(exports, "getPaymentContractInfo", { enumerable: true, get: function () { return payment_1.getPaymentContractInfo; } });
+Object.defineProperty(exports, "createPaymentIntent", { enumerable: true, get: function () { return payment_1.createPaymentIntent; } });
+Object.defineProperty(exports, "watchPaymentTransaction", { enumerable: true, get: function () { return payment_1.watchPaymentTransaction; } });
+Object.defineProperty(exports, "getPaymentIntentStatus", { enumerable: true, get: function () { return payment_1.getPaymentIntentStatus; } });
+Object.defineProperty(exports, "waitForPaymentCompletion", { enumerable: true, get: function () { return payment_1.waitForPaymentCompletion; } });

package/dist/api/calls/payment.d.ts

@@ -0,0 +1,66 @@
+import { PaymentContractInfo, PaymentIntent, PaymentIntentStatus, PaymentIntentTerminalStatus, PollOptions, StoragePrice } from '../models/payment';
+import { AutoDriveApiHandler } from '../types';
+/**
+ * Returns the current live storage price without creating a price-locked intent.
+ *
+ * This is a public endpoint — no API key is required.
+ * Use it to show a cost estimate to users before they commit to a payment.
+ *
+ * @returns `shannonsPerByte` — the raw on-chain price, and `ai3PerGb` — a
+ *   pre-computed display value in AI3 per gigabyte.
+ */
+export declare const getStoragePrice: (api: AutoDriveApiHandler) => Promise<StoragePrice>;
+/**
+ * Fetches the EVM chain ID, contract address, and ABI needed to call `payIntent(bytes32)`.
+ *
+ * This is a public endpoint — no API key is required. The result is stable
+ * per network and safe to cache for the lifetime of the application.
+ */
+export declare const getPaymentContractInfo: (api: AutoDriveApiHandler) => Promise<PaymentContractInfo>;
+/**
+ * Creates a price-locked payment intent for a given upload size in bytes.
+ *
+ * The intent locks the current `shannonsPerByte` price for 10 minutes.
+ * The returned `ai3AmountWei` is the exact value to pass as `msg.value`
+ * when calling `payIntent(intentId)` on the Credits Receiver contract.
+ *
+ * Note: `sizeBytes` is **not** sent to the Auto Drive API. The POST `/intents`
+ * endpoint accepts no request body — it returns the current `shannonsPerByte`
+ * rate. The SDK multiplies that rate by `sizeBytes` to produce `ai3AmountWei`,
+ * saving the caller from doing the BigInt arithmetic themselves.
+ *
+ * Flow:
+ * 1. Call `createPaymentIntent(api, sizeBytes)` — locks the price
+ * 2. Send `intent.ai3AmountWei` to `intent.contractAddress` via `payIntent(intent.intentId)`
+ * 3. Call `watchPaymentTransaction(api, intent.intentId, txHash)` — submit the tx hash
+ * 4. Call `waitForPaymentCompletion(api, intent.intentId)` — poll until COMPLETED
+ */
+export declare const createPaymentIntent: (api: AutoDriveApiHandler, sizeBytes: number) => Promise<PaymentIntent>;
+/**
+ * Notifies Auto Drive that an on-chain transaction has been submitted for a payment intent.
+ *
+ * Auto Drive will watch the transaction on-chain and automatically apply storage
+ * credits to your account once the transaction is confirmed.
+ */
+export declare const watchPaymentTransaction: (api: AutoDriveApiHandler, intentId: string, txHash: string) => Promise<void>;
+/**
+ * Returns the current status of a payment intent.
+ *
+ * Possible statuses: PENDING | CONFIRMED | COMPLETED | EXPIRED | FAILED | OVER_CAP
+ */
+export declare const getPaymentIntentStatus: (api: AutoDriveApiHandler, intentId: string) => Promise<{
+    id: string;
+    status: PaymentIntentStatus;
+}>;
+/**
+ * Polls a payment intent at regular intervals until it reaches a terminal state.
+ *
+ * Returns the terminal status: COMPLETED | EXPIRED | FAILED | OVER_CAP.
+ * Throws if the timeout is exceeded before a terminal state is reached.
+ *
+ * @param api     - An authenticated AutoDriveApiHandler
+ * @param intentId - The intent ID returned by `createPaymentIntent`
+ * @param options - Optional poll interval and timeout (defaults: 3 s / 5 min)
+ */
+export declare const waitForPaymentCompletion: (api: AutoDriveApiHandler, intentId: string, { pollIntervalMs, timeoutMs }?: PollOptions) => Promise<PaymentIntentTerminalStatus>;
+//# sourceMappingURL=payment.d.ts.map

package/dist/api/calls/payment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment.d.ts","sourceRoot":"","sources":["../../../src/api/calls/payment.ts"],"names":[],"mappings":"AACA,OAAO,EACL,mBAAmB,EACnB,aAAa,EACb,mBAAmB,EACnB,2BAA2B,EAC3B,WAAW,EACX,YAAY,EACb,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAA;AAS9C;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,GAAU,KAAK,mBAAmB,KAAG,OAAO,CAAC,YAAY,CASpF,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,GACjC,KAAK,mBAAmB,KACvB,OAAO,CAAC,mBAAmB,CAQ7B,CAAA;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,mBAAmB,GAC9B,KAAK,mBAAmB,EACxB,WAAW,MAAM,KAChB,OAAO,CAAC,aAAa,CAuBvB,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,GAClC,KAAK,mBAAmB,EACxB,UAAU,MAAM,EAChB,QAAQ,MAAM,KACb,OAAO,CAAC,IAAI,CAcd,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,GACjC,KAAK,mBAAmB,EACxB,UAAU,MAAM,KACf,OAAO,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,mBAAmB,CAAA;CAAE,CAUrD,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,wBAAwB,GACnC,KAAK,mBAAmB,EACxB,UAAU,MAAM,EAChB,gCAAiD,WAAgB,KAChE,OAAO,CAAC,2BAA2B,CAgBrC,CAAA"}

package/dist/api/calls/payment.js

@@ -0,0 +1,145 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.waitForPaymentCompletion = exports.getPaymentIntentStatus = exports.watchPaymentTransaction = exports.createPaymentIntent = exports.getPaymentContractInfo = exports.getStoragePrice = void 0;
+const auto_utils_1 = require("@autonomys/auto-utils");
+const TERMINAL_STATUSES = [
+    'COMPLETED',
+    'EXPIRED',
+    'FAILED',
+    'OVER_CAP',
+];
+/**
+ * Returns the current live storage price without creating a price-locked intent.
+ *
+ * This is a public endpoint — no API key is required.
+ * Use it to show a cost estimate to users before they commit to a payment.
+ *
+ * @returns `shannonsPerByte` — the raw on-chain price, and `ai3PerGb` — a
+ *   pre-computed display value in AI3 per gigabyte.
+ */
+const getStoragePrice = (api) => __awaiter(void 0, void 0, void 0, function* () {
+    const response = yield api.sendAPIRequest('/intents/price', { method: 'GET' });
+    if (!response.ok) {
+        throw new Error(`Failed to fetch storage price: ${response.status} ${response.statusText}`);
+    }
+    const { price, pricePerGB } = yield response.json();
+    return { shannonsPerByte: price, ai3PerGb: pricePerGB };
+});
+exports.getStoragePrice = getStoragePrice;
+/**
+ * Fetches the EVM chain ID, contract address, and ABI needed to call `payIntent(bytes32)`.
+ *
+ * This is a public endpoint — no API key is required. The result is stable
+ * per network and safe to cache for the lifetime of the application.
+ */
+const getPaymentContractInfo = (api) => __awaiter(void 0, void 0, void 0, function* () {
+    const response = yield api.sendAPIRequest('/intents/contract', { method: 'GET' });
+    if (!response.ok) {
+        throw new Error(`Failed to fetch payment contract info: ${response.status} ${response.statusText}`);
+    }
+    return response.json();
+});
+exports.getPaymentContractInfo = getPaymentContractInfo;
+/**
+ * Creates a price-locked payment intent for a given upload size in bytes.
+ *
+ * The intent locks the current `shannonsPerByte` price for 10 minutes.
+ * The returned `ai3AmountWei` is the exact value to pass as `msg.value`
+ * when calling `payIntent(intentId)` on the Credits Receiver contract.
+ *
+ * Note: `sizeBytes` is **not** sent to the Auto Drive API. The POST `/intents`
+ * endpoint accepts no request body — it returns the current `shannonsPerByte`
+ * rate. The SDK multiplies that rate by `sizeBytes` to produce `ai3AmountWei`,
+ * saving the caller from doing the BigInt arithmetic themselves.
+ *
+ * Flow:
+ * 1. Call `createPaymentIntent(api, sizeBytes)` — locks the price
+ * 2. Send `intent.ai3AmountWei` to `intent.contractAddress` via `payIntent(intent.intentId)`
+ * 3. Call `watchPaymentTransaction(api, intent.intentId, txHash)` — submit the tx hash
+ * 4. Call `waitForPaymentCompletion(api, intent.intentId)` — poll until COMPLETED
+ */
+const createPaymentIntent = (api, sizeBytes) => __awaiter(void 0, void 0, void 0, function* () {
+    const [contractInfo, intentRes] = yield Promise.all([
+        (0, exports.getPaymentContractInfo)(api),
+        api.sendAPIRequest('/intents', { method: 'POST' }),
+    ]);
+    if (!intentRes.ok) {
+        const body = yield intentRes.text();
+        throw new Error(`Failed to create payment intent: ${intentRes.status} ${body}`);
+    }
+    const intent = yield intentRes.json();
+    const shannonsPerByte = BigInt(intent.shannonsPerByte);
+    const ai3AmountWei = shannonsPerByte * BigInt(sizeBytes);
+    return {
+        intentId: intent.id,
+        ai3AmountWei: ai3AmountWei.toString(),
+        ai3Amount: (0, auto_utils_1.shannonsToAi3)(ai3AmountWei),
+        contractAddress: contractInfo.contractAddress,
+        shannonsPerByte: intent.shannonsPerByte,
+        expiresAt: intent.expiresAt,
+    };
+});
+exports.createPaymentIntent = createPaymentIntent;
+/**
+ * Notifies Auto Drive that an on-chain transaction has been submitted for a payment intent.
+ *
+ * Auto Drive will watch the transaction on-chain and automatically apply storage
+ * credits to your account once the transaction is confirmed.
+ */
+const watchPaymentTransaction = (api, intentId, txHash) => __awaiter(void 0, void 0, void 0, function* () {
+    const response = yield api.sendAPIRequest(`/intents/${intentId}/watch`, {
+        method: 'POST',
+        headers: new Headers({ 'Content-Type': 'application/json' }),
+    }, JSON.stringify({ txHash }));
+    if (!response.ok) {
+        const body = yield response.text();
+        throw new Error(`Failed to watch payment transaction: ${response.status} ${body}`);
+    }
+});
+exports.watchPaymentTransaction = watchPaymentTransaction;
+/**
+ * Returns the current status of a payment intent.
+ *
+ * Possible statuses: PENDING | CONFIRMED | COMPLETED | EXPIRED | FAILED | OVER_CAP
+ */
+const getPaymentIntentStatus = (api, intentId) => __awaiter(void 0, void 0, void 0, function* () {
+    const response = yield api.sendAPIRequest(`/intents/${intentId}`, { method: 'GET' });
+    if (!response.ok) {
+        const body = yield response.text();
+        throw new Error(`Failed to get payment intent status: ${response.status} ${body}`);
+    }
+    const data = yield response.json();
+    return { id: data.id, status: data.status.toUpperCase() };
+});
+exports.getPaymentIntentStatus = getPaymentIntentStatus;
+/**
+ * Polls a payment intent at regular intervals until it reaches a terminal state.
+ *
+ * Returns the terminal status: COMPLETED | EXPIRED | FAILED | OVER_CAP.
+ * Throws if the timeout is exceeded before a terminal state is reached.
+ *
+ * @param api     - An authenticated AutoDriveApiHandler
+ * @param intentId - The intent ID returned by `createPaymentIntent`
+ * @param options - Optional poll interval and timeout (defaults: 3 s / 5 min)
+ */
+const waitForPaymentCompletion = (api_1, intentId_1, ...args_1) => __awaiter(void 0, [api_1, intentId_1, ...args_1], void 0, function* (api, intentId, { pollIntervalMs = 3000, timeoutMs = 300000 } = {}) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const { status } = yield (0, exports.getPaymentIntentStatus)(api, intentId);
+        if (TERMINAL_STATUSES.includes(status)) {
+            return status;
+        }
+        yield new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+    }
+    throw new Error(`Timed out waiting for payment intent "${intentId}" to complete after ${timeoutMs}ms`);
+});
+exports.waitForPaymentCompletion = waitForPaymentCompletion;

package/dist/api/models/index.d.ts

@@ -1,3 +1,4 @@
 export * from './objects';
+export * from './payment';
 export * from './uploads';
 //# sourceMappingURL=index.d.ts.map

package/dist/api/models/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/api/models/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAA;AACzB,cAAc,WAAW,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/api/models/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAA;AACzB,cAAc,WAAW,CAAA;AACzB,cAAc,WAAW,CAAA"}

package/dist/api/models/index.js

@@ -15,4 +15,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./objects"), exports);
+__exportStar(require("./payment"), exports);
 __exportStar(require("./uploads"), exports);

package/dist/api/models/payment.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Current storage price, returned by `getStoragePrice`.
+ * This is a live read of the on-chain byte fee — no API key required.
+ * Use it to display a cost estimate before creating a price-locked intent.
+ */
+export type StoragePrice = {
+    /** Current price per byte in shannons */
+    shannonsPerByte: number;
+    /** Pre-computed display price in AI3 per gigabyte */
+    ai3PerGb: number;
+};
+/**
+ * Information about the EVM smart contract used to pay for storage intents.
+ * Returned by the public `/intents/contract` endpoint — no API key required.
+ */
+export type PaymentContractInfo = {
+    /** Auto EVM chain ID (870 for mainnet) */
+    chainId: number;
+    /** Address of the Credits Receiver contract */
+    contractAddress: string;
+    /** ABI fragment for the payIntent(bytes32) function */
+    payIntentAbi: readonly unknown[];
+};
+/**
+ * A price-locked payment intent returned by `createPaymentIntent`.
+ * The intent expires after 10 minutes. Send exactly `ai3AmountWei` to
+ * the Credits Receiver contract via `payIntent(intentId)`.
+ */
+export type PaymentIntent = {
+    /** Unique intent identifier — pass as the `bytes32` arg to `payIntent()` */
+    intentId: string;
+    /** Amount to send, in shannons/wei, as a decimal string (safe for BigInt conversion) */
+    ai3AmountWei: string;
+    /** Human-readable amount, e.g. "0.00123" */
+    ai3Amount: string;
+    /** The Credits Receiver contract address (convenience copy from PaymentContractInfo) */
+    contractAddress: string;
+    /** Current price per byte in shannons */
+    shannonsPerByte: string;
+    /** ISO 8601 timestamp when this intent expires */
+    expiresAt: string;
+};
+/** All possible states a payment intent can be in */
+export type PaymentIntentStatus = 'PENDING' | 'CONFIRMED' | 'COMPLETED' | 'EXPIRED' | 'FAILED' | 'OVER_CAP';
+/** States that indicate the intent lifecycle has ended */
+export type PaymentIntentTerminalStatus = Extract<PaymentIntentStatus, 'COMPLETED' | 'EXPIRED' | 'FAILED' | 'OVER_CAP'>;
+/** Options for `waitForPaymentCompletion` */
+export type PollOptions = {
+    /** How often to check intent status. Default: 3 000 ms */
+    pollIntervalMs?: number;
+    /** Maximum time to wait before throwing. Default: 300 000 ms (5 minutes) */
+    timeoutMs?: number;
+};
+//# sourceMappingURL=payment.d.ts.map

package/dist/api/models/payment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment.d.ts","sourceRoot":"","sources":["../../../src/api/models/payment.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,yCAAyC;IACzC,eAAe,EAAE,MAAM,CAAA;IACvB,qDAAqD;IACrD,QAAQ,EAAE,MAAM,CAAA;CACjB,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAA;IACf,+CAA+C;IAC/C,eAAe,EAAE,MAAM,CAAA;IACvB,uDAAuD;IACvD,YAAY,EAAE,SAAS,OAAO,EAAE,CAAA;CACjC,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,4EAA4E;IAC5E,QAAQ,EAAE,MAAM,CAAA;IAChB,wFAAwF;IACxF,YAAY,EAAE,MAAM,CAAA;IACpB,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAA;IACjB,wFAAwF;IACxF,eAAe,EAAE,MAAM,CAAA;IACvB,yCAAyC;IACzC,eAAe,EAAE,MAAM,CAAA;IACvB,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAA;CAClB,CAAA;AAED,qDAAqD;AACrD,MAAM,MAAM,mBAAmB,GAC3B,SAAS,GACT,WAAW,GACX,WAAW,GACX,SAAS,GACT,QAAQ,GACR,UAAU,CAAA;AAEd,0DAA0D;AAC1D,MAAM,MAAM,2BAA2B,GAAG,OAAO,CAC/C,mBAAmB,EACnB,WAAW,GAAG,SAAS,GAAG,QAAQ,GAAG,UAAU,CAChD,CAAA;AAED,6CAA6C;AAC7C,MAAM,MAAM,WAAW,GAAG;IACxB,0DAA0D;IAC1D,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA"}

package/dist/api/models/payment.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/api/types.d.ts

@@ -2,6 +2,7 @@ import { ObjectSummary } from './models';
 import { AsyncDownload } from './models/asyncDownloads';
 import { PaginatedResult } from './models/common';
 import { GenericFile, GenericFileWithinFolder } from './models/file';
+import { PaymentContractInfo, PaymentIntent, PaymentIntentStatus, PaymentIntentTerminalStatus, PollOptions, StoragePrice } from './models/payment';
 import { SubscriptionInfo, UserInfo } from './models/user';
 import { AutoDriveNetwork } from './networks';
 export interface AutoDriveApi extends AutoDriveApiHandler {
@@ -137,6 +138,68 @@ export interface AutoDriveApi extends AutoDriveApiHandler {
      * @returns {Promise<SubscriptionInfo>} A promise that resolves to the subscription info.
      */
     getSubscriptionInfo: () => Promise<SubscriptionInfo>;
+    /**
+     * Returns the current live storage price without creating a price-locked intent.
+     *
+     * This is a public endpoint — no API key required.
+     * Use it to display a cost estimate to users before they commit to a payment.
+     *
+     * @returns {Promise<StoragePrice>} Current price per byte and a pre-computed AI3/GB display value.
+     */
+    getStoragePrice: () => Promise<StoragePrice>;
+    /**
+     * Fetches the EVM chain ID, contract address, and ABI for the Credits Receiver contract.
+     *
+     * This is a public endpoint — no API key required. The result is stable per network
+     * and safe to cache for the lifetime of the application.
+     *
+     * @returns {Promise<PaymentContractInfo>} Chain details needed to call `payIntent(bytes32)`.
+     */
+    getPaymentContractInfo: () => Promise<PaymentContractInfo>;
+    /**
+     * Creates a price-locked payment intent for a given upload size.
+     *
+     * The intent locks the current storage price for 10 minutes. Send exactly
+     * `intent.ai3AmountWei` to the Credits Receiver contract via `payIntent(intent.intentId)`,
+     * then call `watchPaymentTransaction` to notify Auto Drive.
+     *
+     * @param sizeBytes - Upload size in bytes. Used **by the SDK** to compute
+     *   `ai3AmountWei = shannonsPerByte × sizeBytes`. It is not sent to the server —
+     *   the POST `/intents` endpoint accepts no request body.
+     * @returns {Promise<PaymentIntent>} Intent details including amount, contract address, and expiry.
+     */
+    createPaymentIntent: (sizeBytes: number) => Promise<PaymentIntent>;
+    /**
+     * Notifies Auto Drive that an on-chain transaction has been submitted for a payment intent.
+     *
+     * Auto Drive will watch the transaction and automatically apply storage credits
+     * to your account once confirmed on-chain.
+     *
+     * @param intentId - The intent ID from `createPaymentIntent`.
+     * @param txHash   - The on-chain transaction hash.
+     */
+    watchPaymentTransaction: (intentId: string, txHash: string) => Promise<void>;
+    /**
+     * Returns the current status of a payment intent.
+     *
+     * Possible statuses: PENDING | CONFIRMED | COMPLETED | EXPIRED | FAILED | OVER_CAP
+     *
+     * @param intentId - The intent ID from `createPaymentIntent`.
+     */
+    getPaymentIntentStatus: (intentId: string) => Promise<{
+        id: string;
+        status: PaymentIntentStatus;
+    }>;
+    /**
+     * Polls a payment intent until it reaches a terminal state.
+     *
+     * Returns the terminal status: COMPLETED | EXPIRED | FAILED | OVER_CAP.
+     * Throws if the timeout is exceeded before a terminal state is reached.
+     *
+     * @param intentId - The intent ID from `createPaymentIntent`.
+     * @param options  - Optional poll interval and timeout (defaults: 3 s / 5 min).
+     */
+    waitForPaymentCompletion: (intentId: string, options?: PollOptions) => Promise<PaymentIntentTerminalStatus>;
     /**
      * Publishes an object by sending a request to the server.
      *

package/dist/api/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/api/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/api/types.ts"],"names":[],"mappings":"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"}

package/dist/api/wrappers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wrappers.d.ts","sourceRoot":"","sources":["../../src/api/wrappers.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAqB,MAAM,SAAS,CAAA;AA6B9E,eAAO,MAAM,kBAAkB,GAAI,KAAK,mBAAmB,KAAG,YA4V7D,CAAA"}
+{"version":3,"file":"wrappers.d.ts","sourceRoot":"","sources":["../../src/api/wrappers.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAqB,MAAM,SAAS,CAAA;AA6B9E,eAAO,MAAM,kBAAkB,GAAI,KAAK,mBAAmB,KAAG,YAkX7D,CAAA"}

package/dist/api/wrappers.js

@@ -246,6 +246,12 @@ const createApiInterface = (api) => {
         const me = yield index_1.apiCalls.getMe(api);
         return me.subscription;
     });
+    const getStoragePrice = () => index_1.apiCalls.getStoragePrice(api);
+    const getPaymentContractInfo = () => index_1.apiCalls.getPaymentContractInfo(api);
+    const createPaymentIntent = (sizeBytes) => index_1.apiCalls.createPaymentIntent(api, sizeBytes);
+    const watchPaymentTransaction = (intentId, txHash) => index_1.apiCalls.watchPaymentTransaction(api, intentId, txHash);
+    const getPaymentIntentStatus = (intentId) => index_1.apiCalls.getPaymentIntentStatus(api, intentId);
+    const waitForPaymentCompletion = (intentId, options) => index_1.apiCalls.waitForPaymentCompletion(api, intentId, options);
     const publishObject = (cid) => __awaiter(void 0, void 0, void 0, function* () {
         const result = yield index_1.apiCalls.publishObject(api, { cid });
         return (0, download_1.publicDownloadUrl)(api, result.result);
@@ -280,6 +286,12 @@ const createApiInterface = (api) => {
         downloadFile,
         getPendingCredits,
         getSubscriptionInfo,
+        getStoragePrice,
+        getPaymentContractInfo,
+        createPaymentIntent,
+        watchPaymentTransaction,
+        getPaymentIntentStatus,
+        waitForPaymentCompletion,
         publishObject,
         getMyFiles,
         searchByNameOrCIDInMyFiles,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@autonomys/auto-drive",
   "packageManager": "yarn@4.7.0",
-  "version": "1.6.8",
+  "version": "1.6.10",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -42,9 +42,9 @@
     "typescript": "^5.8.3"
   },
   "dependencies": {
-    "@autonomys/asynchronous": "^1.6.8",
-    "@autonomys/auto-dag-data": "^1.6.8",
-    "@autonomys/auto-utils": "^1.6.8",
+    "@autonomys/asynchronous": "^1.6.10",
+    "@autonomys/auto-dag-data": "^1.6.10",
+    "@autonomys/auto-utils": "^1.6.10",
     "blockstore-core": "^5.0.2",
     "jszip": "^3.10.1",
     "mime-types": "^3.0.2",
@@ -52,5 +52,5 @@
     "stream": "^0.0.3",
     "zod": "^3.24.2"
   },
-  "gitHead": "5ebe5b10511fe9f1ddc348e5f50fe6f843bddca3"
+  "gitHead": "ff14841a080170350d57df19327f484c8b95f874"
 }

package/src/api/calls/index.ts

@@ -1,11 +1,24 @@
 import * as downloadCalls from './download'
+import * as paymentCalls from './payment'
 import * as readCalls from './read'
 import * as uploadCalls from './upload'
 import * as writeCalls from './write'
 
 export const apiCalls = {
   ...downloadCalls,
+  ...paymentCalls,
   ...readCalls,
   ...uploadCalls,
   ...writeCalls,
 }
+
+// Re-export payment utilities as named exports so callers can use them
+// as standalone functions without going through the apiCalls object.
+export {
+  getStoragePrice,
+  getPaymentContractInfo,
+  createPaymentIntent,
+  watchPaymentTransaction,
+  getPaymentIntentStatus,
+  waitForPaymentCompletion,
+} from './payment'

package/src/api/calls/payment.ts

@@ -0,0 +1,179 @@
+import { shannonsToAi3 } from '@autonomys/auto-utils'
+import {
+  PaymentContractInfo,
+  PaymentIntent,
+  PaymentIntentStatus,
+  PaymentIntentTerminalStatus,
+  PollOptions,
+  StoragePrice,
+} from '../models/payment'
+import { AutoDriveApiHandler } from '../types'
+
+const TERMINAL_STATUSES: PaymentIntentTerminalStatus[] = [
+  'COMPLETED',
+  'EXPIRED',
+  'FAILED',
+  'OVER_CAP',
+]
+
+/**
+ * Returns the current live storage price without creating a price-locked intent.
+ *
+ * This is a public endpoint — no API key is required.
+ * Use it to show a cost estimate to users before they commit to a payment.
+ *
+ * @returns `shannonsPerByte` — the raw on-chain price, and `ai3PerGb` — a
+ *   pre-computed display value in AI3 per gigabyte.
+ */
+export const getStoragePrice = async (api: AutoDriveApiHandler): Promise<StoragePrice> => {
+  const response = await api.sendAPIRequest('/intents/price', { method: 'GET' })
+
+  if (!response.ok) {
+    throw new Error(`Failed to fetch storage price: ${response.status} ${response.statusText}`)
+  }
+
+  const { price, pricePerGB } = await response.json()
+  return { shannonsPerByte: price, ai3PerGb: pricePerGB }
+}
+
+/**
+ * Fetches the EVM chain ID, contract address, and ABI needed to call `payIntent(bytes32)`.
+ *
+ * This is a public endpoint — no API key is required. The result is stable
+ * per network and safe to cache for the lifetime of the application.
+ */
+export const getPaymentContractInfo = async (
+  api: AutoDriveApiHandler,
+): Promise<PaymentContractInfo> => {
+  const response = await api.sendAPIRequest('/intents/contract', { method: 'GET' })
+
+  if (!response.ok) {
+    throw new Error(`Failed to fetch payment contract info: ${response.status} ${response.statusText}`)
+  }
+
+  return response.json()
+}
+
+/**
+ * Creates a price-locked payment intent for a given upload size in bytes.
+ *
+ * The intent locks the current `shannonsPerByte` price for 10 minutes.
+ * The returned `ai3AmountWei` is the exact value to pass as `msg.value`
+ * when calling `payIntent(intentId)` on the Credits Receiver contract.
+ *
+ * Note: `sizeBytes` is **not** sent to the Auto Drive API. The POST `/intents`
+ * endpoint accepts no request body — it returns the current `shannonsPerByte`
+ * rate. The SDK multiplies that rate by `sizeBytes` to produce `ai3AmountWei`,
+ * saving the caller from doing the BigInt arithmetic themselves.
+ *
+ * Flow:
+ * 1. Call `createPaymentIntent(api, sizeBytes)` — locks the price
+ * 2. Send `intent.ai3AmountWei` to `intent.contractAddress` via `payIntent(intent.intentId)`
+ * 3. Call `watchPaymentTransaction(api, intent.intentId, txHash)` — submit the tx hash
+ * 4. Call `waitForPaymentCompletion(api, intent.intentId)` — poll until COMPLETED
+ */
+export const createPaymentIntent = async (
+  api: AutoDriveApiHandler,
+  sizeBytes: number,
+): Promise<PaymentIntent> => {
+  const [contractInfo, intentRes] = await Promise.all([
+    getPaymentContractInfo(api),
+    api.sendAPIRequest('/intents', { method: 'POST' }),
+  ])
+
+  if (!intentRes.ok) {
+    const body = await intentRes.text()
+    throw new Error(`Failed to create payment intent: ${intentRes.status} ${body}`)
+  }
+
+  const intent = await intentRes.json()
+  const shannonsPerByte = BigInt(intent.shannonsPerByte)
+  const ai3AmountWei = shannonsPerByte * BigInt(sizeBytes)
+
+  return {
+    intentId: intent.id,
+    ai3AmountWei: ai3AmountWei.toString(),
+    ai3Amount: shannonsToAi3(ai3AmountWei),
+    contractAddress: contractInfo.contractAddress,
+    shannonsPerByte: intent.shannonsPerByte,
+    expiresAt: intent.expiresAt,
+  }
+}
+
+/**
+ * Notifies Auto Drive that an on-chain transaction has been submitted for a payment intent.
+ *
+ * Auto Drive will watch the transaction on-chain and automatically apply storage
+ * credits to your account once the transaction is confirmed.
+ */
+export const watchPaymentTransaction = async (
+  api: AutoDriveApiHandler,
+  intentId: string,
+  txHash: string,
+): Promise<void> => {
+  const response = await api.sendAPIRequest(
+    `/intents/${intentId}/watch`,
+    {
+      method: 'POST',
+      headers: new Headers({ 'Content-Type': 'application/json' }),
+    },
+    JSON.stringify({ txHash }),
+  )
+
+  if (!response.ok) {
+    const body = await response.text()
+    throw new Error(`Failed to watch payment transaction: ${response.status} ${body}`)
+  }
+}
+
+/**
+ * Returns the current status of a payment intent.
+ *
+ * Possible statuses: PENDING | CONFIRMED | COMPLETED | EXPIRED | FAILED | OVER_CAP
+ */
+export const getPaymentIntentStatus = async (
+  api: AutoDriveApiHandler,
+  intentId: string,
+): Promise<{ id: string; status: PaymentIntentStatus }> => {
+  const response = await api.sendAPIRequest(`/intents/${intentId}`, { method: 'GET' })
+
+  if (!response.ok) {
+    const body = await response.text()
+    throw new Error(`Failed to get payment intent status: ${response.status} ${body}`)
+  }
+
+  const data = await response.json()
+  return { id: data.id, status: data.status.toUpperCase() as PaymentIntentStatus }
+}
+
+/**
+ * Polls a payment intent at regular intervals until it reaches a terminal state.
+ *
+ * Returns the terminal status: COMPLETED | EXPIRED | FAILED | OVER_CAP.
+ * Throws if the timeout is exceeded before a terminal state is reached.
+ *
+ * @param api     - An authenticated AutoDriveApiHandler
+ * @param intentId - The intent ID returned by `createPaymentIntent`
+ * @param options - Optional poll interval and timeout (defaults: 3 s / 5 min)
+ */
+export const waitForPaymentCompletion = async (
+  api: AutoDriveApiHandler,
+  intentId: string,
+  { pollIntervalMs = 3_000, timeoutMs = 300_000 }: PollOptions = {},
+): Promise<PaymentIntentTerminalStatus> => {
+  const deadline = Date.now() + timeoutMs
+
+  while (Date.now() < deadline) {
+    const { status } = await getPaymentIntentStatus(api, intentId)
+
+    if ((TERMINAL_STATUSES as string[]).includes(status)) {
+      return status as PaymentIntentTerminalStatus
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, pollIntervalMs))
+  }
+
+  throw new Error(
+    `Timed out waiting for payment intent "${intentId}" to complete after ${timeoutMs}ms`,
+  )
+}

package/src/api/models/index.ts

@@ -1,2 +1,3 @@
 export * from './objects'
+export * from './payment'
 export * from './uploads'

package/src/api/models/payment.ts

@@ -0,0 +1,67 @@
+/**
+ * Current storage price, returned by `getStoragePrice`.
+ * This is a live read of the on-chain byte fee — no API key required.
+ * Use it to display a cost estimate before creating a price-locked intent.
+ */
+export type StoragePrice = {
+  /** Current price per byte in shannons */
+  shannonsPerByte: number
+  /** Pre-computed display price in AI3 per gigabyte */
+  ai3PerGb: number
+}
+
+/**
+ * Information about the EVM smart contract used to pay for storage intents.
+ * Returned by the public `/intents/contract` endpoint — no API key required.
+ */
+export type PaymentContractInfo = {
+  /** Auto EVM chain ID (870 for mainnet) */
+  chainId: number
+  /** Address of the Credits Receiver contract */
+  contractAddress: string
+  /** ABI fragment for the payIntent(bytes32) function */
+  payIntentAbi: readonly unknown[]
+}
+
+/**
+ * A price-locked payment intent returned by `createPaymentIntent`.
+ * The intent expires after 10 minutes. Send exactly `ai3AmountWei` to
+ * the Credits Receiver contract via `payIntent(intentId)`.
+ */
+export type PaymentIntent = {
+  /** Unique intent identifier — pass as the `bytes32` arg to `payIntent()` */
+  intentId: string
+  /** Amount to send, in shannons/wei, as a decimal string (safe for BigInt conversion) */
+  ai3AmountWei: string
+  /** Human-readable amount, e.g. "0.00123" */
+  ai3Amount: string
+  /** The Credits Receiver contract address (convenience copy from PaymentContractInfo) */
+  contractAddress: string
+  /** Current price per byte in shannons */
+  shannonsPerByte: string
+  /** ISO 8601 timestamp when this intent expires */
+  expiresAt: string
+}
+
+/** All possible states a payment intent can be in */
+export type PaymentIntentStatus =
+  | 'PENDING'
+  | 'CONFIRMED'
+  | 'COMPLETED'
+  | 'EXPIRED'
+  | 'FAILED'
+  | 'OVER_CAP'
+
+/** States that indicate the intent lifecycle has ended */
+export type PaymentIntentTerminalStatus = Extract<
+  PaymentIntentStatus,
+  'COMPLETED' | 'EXPIRED' | 'FAILED' | 'OVER_CAP'
+>
+
+/** Options for `waitForPaymentCompletion` */
+export type PollOptions = {
+  /** How often to check intent status. Default: 3 000 ms */
+  pollIntervalMs?: number
+  /** Maximum time to wait before throwing. Default: 300 000 ms (5 minutes) */
+  timeoutMs?: number
+}

package/src/api/types.ts

@@ -2,6 +2,14 @@ import { ObjectSummary } from './models'
 import { AsyncDownload } from './models/asyncDownloads'
 import { PaginatedResult } from './models/common'
 import { GenericFile, GenericFileWithinFolder } from './models/file'
+import {
+  PaymentContractInfo,
+  PaymentIntent,
+  PaymentIntentStatus,
+  PaymentIntentTerminalStatus,
+  PollOptions,
+  StoragePrice,
+} from './models/payment'
 import { SubscriptionInfo, UserInfo } from './models/user'
 import { AutoDriveNetwork } from './networks'
 
@@ -163,6 +171,79 @@ export interface AutoDriveApi extends AutoDriveApiHandler {
    * @returns {Promise<SubscriptionInfo>} A promise that resolves to the subscription info.
    */
   getSubscriptionInfo: () => Promise<SubscriptionInfo>
+
+  // ---------------------------------------------------------------------------
+  // Pay with AI3 — credit purchase via on-chain payment intent
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Returns the current live storage price without creating a price-locked intent.
+   *
+   * This is a public endpoint — no API key required.
+   * Use it to display a cost estimate to users before they commit to a payment.
+   *
+   * @returns {Promise<StoragePrice>} Current price per byte and a pre-computed AI3/GB display value.
+   */
+  getStoragePrice: () => Promise<StoragePrice>
+
+  /**
+   * Fetches the EVM chain ID, contract address, and ABI for the Credits Receiver contract.
+   *
+   * This is a public endpoint — no API key required. The result is stable per network
+   * and safe to cache for the lifetime of the application.
+   *
+   * @returns {Promise<PaymentContractInfo>} Chain details needed to call `payIntent(bytes32)`.
+   */
+  getPaymentContractInfo: () => Promise<PaymentContractInfo>
+
+  /**
+   * Creates a price-locked payment intent for a given upload size.
+   *
+   * The intent locks the current storage price for 10 minutes. Send exactly
+   * `intent.ai3AmountWei` to the Credits Receiver contract via `payIntent(intent.intentId)`,
+   * then call `watchPaymentTransaction` to notify Auto Drive.
+   *
+   * @param sizeBytes - Upload size in bytes. Used **by the SDK** to compute
+   *   `ai3AmountWei = shannonsPerByte × sizeBytes`. It is not sent to the server —
+   *   the POST `/intents` endpoint accepts no request body.
+   * @returns {Promise<PaymentIntent>} Intent details including amount, contract address, and expiry.
+   */
+  createPaymentIntent: (sizeBytes: number) => Promise<PaymentIntent>
+
+  /**
+   * Notifies Auto Drive that an on-chain transaction has been submitted for a payment intent.
+   *
+   * Auto Drive will watch the transaction and automatically apply storage credits
+   * to your account once confirmed on-chain.
+   *
+   * @param intentId - The intent ID from `createPaymentIntent`.
+   * @param txHash   - The on-chain transaction hash.
+   */
+  watchPaymentTransaction: (intentId: string, txHash: string) => Promise<void>
+
+  /**
+   * Returns the current status of a payment intent.
+   *
+   * Possible statuses: PENDING | CONFIRMED | COMPLETED | EXPIRED | FAILED | OVER_CAP
+   *
+   * @param intentId - The intent ID from `createPaymentIntent`.
+   */
+  getPaymentIntentStatus: (intentId: string) => Promise<{ id: string; status: PaymentIntentStatus }>
+
+  /**
+   * Polls a payment intent until it reaches a terminal state.
+   *
+   * Returns the terminal status: COMPLETED | EXPIRED | FAILED | OVER_CAP.
+   * Throws if the timeout is exceeded before a terminal state is reached.
+   *
+   * @param intentId - The intent ID from `createPaymentIntent`.
+   * @param options  - Optional poll interval and timeout (defaults: 3 s / 5 min).
+   */
+  waitForPaymentCompletion: (
+    intentId: string,
+    options?: PollOptions,
+  ) => Promise<PaymentIntentTerminalStatus>
+
   /**
    * Publishes an object by sending a request to the server.
    *

package/src/api/wrappers.ts

@@ -10,6 +10,7 @@ import mime from 'mime-types'
 import { progressToPercentage } from '../utils/misc'
 import { publicDownloadUrl } from './calls/download'
 import { apiCalls } from './calls/index'
+import { PollOptions } from './models/payment'
 import { ObjectSummary, Scope } from './models'
 import { DownloadStatus } from './models/asyncDownloads'
 import { PaginatedResult } from './models/common'
@@ -320,6 +321,22 @@ export const createApiInterface = (api: AutoDriveApiHandler): AutoDriveApi => {
     return me.subscription
   }
 
+  const getStoragePrice = () => apiCalls.getStoragePrice(api)
+
+  const getPaymentContractInfo = () => apiCalls.getPaymentContractInfo(api)
+
+  const createPaymentIntent = (sizeBytes: number) =>
+    apiCalls.createPaymentIntent(api, sizeBytes)
+
+  const watchPaymentTransaction = (intentId: string, txHash: string) =>
+    apiCalls.watchPaymentTransaction(api, intentId, txHash)
+
+  const getPaymentIntentStatus = (intentId: string) =>
+    apiCalls.getPaymentIntentStatus(api, intentId)
+
+  const waitForPaymentCompletion = (intentId: string, options?: PollOptions) =>
+    apiCalls.waitForPaymentCompletion(api, intentId, options)
+
   const publishObject = async (cid: string): Promise<string> => {
     const result = await apiCalls.publishObject(api, { cid })
 
@@ -372,6 +389,12 @@ export const createApiInterface = (api: AutoDriveApiHandler): AutoDriveApi => {
     downloadFile,
     getPendingCredits,
     getSubscriptionInfo,
+    getStoragePrice,
+    getPaymentContractInfo,
+    createPaymentIntent,
+    watchPaymentTransaction,
+    getPaymentIntentStatus,
+    waitForPaymentCompletion,
     publishObject,
     getMyFiles,
     searchByNameOrCIDInMyFiles,