Auto-Drive SDK — Available Functions

All functions are available as methods on the AutoDriveApi instance returned by createAutoDriveApi. Upload functions that operate on the local filesystem (Node.js only) are accessed via the fs sub-module.

import { createAutoDriveApi, fs } from '@autonomys/auto-drive'
import { NetworkId } from '@autonomys/auto-utils'
 
const api = createAutoDriveApi({ apiKey: 'your-api-key', network: NetworkId.MAINNET })

Upload Operations

api.uploadFile(file, options?, uploadChunkSize?): Promise<string> — Uploads a GenericFile (custom async-iterable interface) with optional encryption and compression. Returns the CID.
fs.uploadFileFromFilepath(api, filePath, options?): Promise<string> — Node.js only. Uploads a file from a local filesystem path with optional encryption and compression. Returns the CID.
api.uploadFileFromInput(file, options?, uploadChunkSize?): Promise<string> — Uploads a browser File object (e.g. from an <input type="file"> event). Returns the CID.
api.uploadFileFromBuffer(buffer, name, options?, uploadChunkSize?): Promise<string> — Uploads a Buffer directly with a given filename. Returns the CID.
api.uploadObjectAsJSON(object, name?, options?, uploadChunkSize?): Promise<string> — Serializes any value as JSON and uploads it. Returns the CID.
api.uploadFolderFromInput(fileList, options?): Promise<string> — Uploads a browser FileList or File[] array as a folder. Returns the root CID.
api.uploadFileWithinFolderUpload(uploadId, file, uploadChunkSize?, options?): Promise<string> — Uploads a single file into an existing folder upload session identified by uploadId. Returns the CID.

UploadFileOptions

type UploadFileOptions = {
  password?: string         // enables AES-256-GCM client-side encryption
  compression?: boolean
  onProgress?: (progress: number) => void
}

Download Operations

api.downloadFile(cid, password?): Promise<AsyncIterable<Buffer>> — Downloads a file by CID. Pass the same password used at upload time to decrypt.
api.publishObject(cid): Promise<string> — Creates a publicly accessible download URL for the given CID. Returns the URL string.
api.isFileCached(cid): Promise<boolean> — Returns whether the file is currently cached and immediately available for download.
api.createAsyncDownload(cid): Promise<AsyncDownload> — Queues a large file for async background download. Returns an AsyncDownload descriptor.
api.getAsyncDownloads(): Promise<AsyncDownload[]> — Returns all active async download jobs for the current account.
api.getAsyncDownload(downloadId): Promise<AsyncDownload> — Returns the status of a single async download by ID.
api.dismissAsyncDownload(downloadId): Promise<void> — Removes a completed or failed async download from the queue.

File Discovery

api.getMyFiles(page, limit): Promise<PaginatedResult<ObjectSummary>> — Returns a paginated list of the current user’s uploaded files.
api.searchByNameOrCIDInMyFiles(value): Promise<ObjectSummary[]> — Searches for files by name or CID within the current user’s files.
api.searchByNameOrCID(value): Promise<ObjectSummary[]> — Global search across all public files by name or CID.

Account and Credits

api.me(): Promise<UserInfo> — Returns the current authenticated user’s profile information.
api.getPendingCredits(): Promise<{ upload: number; download: number }> — Returns the current user’s remaining upload and download credit balances.
api.getSubscriptionInfo(): Promise<SubscriptionInfo> — Returns the current user’s subscription tier and allocation details.
api.getStoragePrice(): Promise<StoragePrice> — Returns the current live storage price from the protocol. No API key required.

type StoragePrice = {
  shannonsPerByte: number
  ai3PerGb: number
}

Pay with AI3 — Payment Intents

These functions implement the complete Pay with AI3 credit purchase flow. See the developer integration guide for full examples.

Four-step flow:

1. createPaymentIntent(sizeBytes)         — locks price, returns amount + contract details
2. send ai3AmountWei to contractAddress   — call payIntent(intentId) on-chain (your wallet code)
3. watchPaymentTransaction(id, txHash)    — notify Auto Drive of the transaction hash
4. waitForPaymentCompletion(id)           — poll until COMPLETED (credits applied)

api.getPaymentContractInfo(): Promise<PaymentContractInfo> — Returns the Auto-EVM contract address, chain ID, and payIntent ABI. No API key required. Called internally by createPaymentIntent; export this for client-side wallet pre-fetching.
api.createPaymentIntent(sizeBytes, options?): Promise<PaymentIntent> — Locks the current storage price for the authenticated account and returns a payment intent. The price is locked for 10 minutes. Pass { checkCreditCap: true } to have Auto Drive refuse to create the intent (403 CREDIT_CAP_EXCEEDED) when the purchase would exceed the account’s credit cap, instead of accepting a payment that ends as OVER_CAP.
api.watchPaymentTransaction(intentId, txHash): Promise<void> — Submits the on-chain transaction hash to Auto Drive. The backend waits for 6 block confirmations before granting credits. Works for both AI3 and USDC intents.
api.getPaymentIntentStatus(intentId): Promise<{ id: string; status: PaymentIntentStatus }> — Returns the current status of a payment intent.
api.waitForPaymentCompletion(intentId, options?): Promise<PaymentIntentTerminalStatus> — Polls until the intent reaches a terminal state (COMPLETED, EXPIRED, FAILED, or OVER_CAP). Resolves with the terminal status. Set options.settleGraceMs to keep polling through an HTTP 410 after the price lock lapses; without it, a 410 throws a PaymentApiError.

The authenticated payment calls throw a PaymentApiError (with status and, for coded backend errors, code) when Auto Drive answers with a non-OK status. See Handling Errors.

Supporting types:

type PaymentContractInfo = {
  chainId: number
  contractAddress: string
  payIntentAbi: readonly unknown[]
}
 
type PaymentIntent = {
  intentId: string
  ai3AmountWei: string   // exact value to send as msg.value (in Shannons)
  ai3Amount: string      // human-readable AI3 amount
  contractAddress: string
  shannonsPerByte: string
  expiresAt: string      // ISO 8601 timestamp, 10 minutes from creation
}
 
type PaymentIntentStatus =
  | 'PENDING'    // awaiting on-chain payment
  | 'CONFIRMED'  // payment received, awaiting final credit grant
  | 'COMPLETED'  // credits applied to account
  | 'EXPIRED'    // no payment received within 10 minutes
  | 'FAILED'     // payment amount below quoted price
  | 'OVER_CAP'   // account's 100 GB limit would be exceeded
 
type PaymentIntentTerminalStatus = 'COMPLETED' | 'EXPIRED' | 'FAILED' | 'OVER_CAP'
 
type PollOptions = {
  pollIntervalMs?: number  // default: 3000
  timeoutMs?: number       // default: 300000 (5 minutes)
  settleGraceMs?: number   // keep polling through HTTP 410 for this long, then return 'EXPIRED'
}
 
type CreatePaymentIntentOptions = {
  checkCreditCap?: boolean // send sizeBytes as requestedBytes for a pre-payment cap check. Default: false
}
 
class PaymentApiError extends Error {
  readonly status: number                       // HTTP status
  readonly code?: PaymentErrorCode | string     // machine-readable backend code, when present
}
 
type PaymentErrorCode =
  | 'GOOGLE_ACCOUNT_REQUIRED'    // 403
  | 'CREDIT_CAP_EXCEEDED'        // 403
  | 'USDC_PAYMENTS_DISABLED'     // 403
  | 'USDC_PAYMENTS_UNAVAILABLE'  // 503
  | 'PRICE_ORACLE_UNAVAILABLE'   // 503
  | 'PRICE_UNSTABLE'             // 503

Pay with USDC — Payment Intents

These functions implement the Pay with USDC credit purchase flow (USDC on Ethereum mainnet). The SDK does not sign transactions: it returns the quote and where to pay, plus typed ABIs, and your wallet library sends the transactions. See the developer integration guide for a full example.

Requires @autonomys/auto-drive v1.6.16 or later.

Five-step flow:

1. createUsdcPaymentIntent(sizeBytes)                 — locks a USDC price, returns amount + chain, token and receiver
2. approve(receiverAddress, usdcAmount)               — on tokenAddress, on chainId (your wallet code)
3. payIntentWithToken(intentId, usdcAmount)           — on receiverAddress, no value (your wallet code)
4. watchPaymentTransaction(id, txHash)                — the hash from step 3, not step 2
5. waitForPaymentCompletion(id, { settleGraceMs })    — poll until COMPLETED (credits applied)

api.getUsdcPaymentTarget(): Promise<UsdcPaymentTarget> — Returns where to send a USDC payment: chain ID, receiver address, token address, token decimals, confirmations, and settleGraceMs. Requires an API key. Called internally by createUsdcPaymentIntent.
api.createUsdcPaymentIntent(sizeBytes: number | bigint): Promise<UsdcPaymentIntent> — Locks a USDC price for sizeBytes of storage and returns the exact amount to pay together with where to pay it. The price is locked for 10 minutes.
erc20ApprovalAbi — Minimal ERC-20 ABI (approve, allowance, balanceOf) for the approval step. transfer and transferFrom are left out on purpose.
usdcReceiverAbi — Minimal ABI for payIntentWithToken(bytes32 intentId, uint256 amount) on AutoDriveUSDCReceiver.

watchPaymentTransaction, getPaymentIntentStatus and waitForPaymentCompletion are shared with the AI3 flow (see above).

Supporting types:

type PaymentMethod = 'ai3_native' | 'usdc_eth'
 
type UsdcPaymentTarget = {
  chainId: number          // EIP-155 chain ID (1 for Ethereum mainnet)
  receiverAddress: string  // AutoDriveUSDCReceiver — also the approve spender
  tokenAddress: string     // USDC token address — call approve on this
  tokenDecimals: number    // 6 for USDC
  confirmations: number    // blocks the backend waits for before crediting
  settleGraceMs: number    // pass to waitForPaymentCompletion
}
 
type UsdcPaymentIntent = {
  intentId: string             // bytes32 arg to payIntentWithToken()
  paymentMethod: 'usdc_eth'
  usdcAmount: string           // exact amount in base units (6 decimals), BigInt-safe string
  usdcAmountFormatted: string  // human-readable, e.g. "27.498"
  receiverAddress: string
  tokenAddress: string
  chainId: number
  tokenDecimals: number
  confirmations: number
  settleGraceMs: number
  expiresAt: string            // ISO 8601 timestamp when the price lock ends
  shannonsPerByte: string      // locked AI3 price per byte
  quotedAi3Shannons: string    // AI3 amount the USDC quote was made for
  usdRateAtCreation: string    // AI3/USD rate × 1e18, for reporting only
}

Create an API Key Pay with AI3 & USDC