run402-mcp/sdk/dist/namespaces/wallets.d.ts

MCP server for Run402 — full-stack backend infrastructure for AI agents: Postgres, auth, storage, serverless functions and atomic deploys. Paid with x402/MPP. Includes $0.03 image generation.

/**
 * `wallets` namespace — the agent's local wallet and its server-side label.
 *
 * `status`, `create`, and `export` touch the local wallet file (`wallet.json`)
 * through optional provider methods; sandbox providers that don't implement
 * them report `{configured: false}` or throw a descriptive error. `faucet`
 * requests testnet USDC into the wallet and works in any environment.
 *
 * The label is the cross-machine / WEB-visible human name for a wallet (e.g.
 * "kychon"), stored server-side keyed by the wallet address and authenticated
 * by the wallet's SIWX signature. It is display metadata only — never key
 * material, no custody.
 *
 * Both label methods are intentionally BEST-EFFORT: they swallow errors (including a
 * not-yet-deployed endpoint / 404 / offline) and return a null/`ok:false`
 * sentinel instead of throwing. This lets `run402 wallets new|rename|import`
 * stay fully functional locally and before the gateway endpoint ships — the
 * local folder name is always the source of truth; the server label is a
 * mirror that catches up.
 *
 * Canonical call shape is the wallet-scoped handle: `r.wallet(address)` →
 * `.getLabel()` / `.setLabel(label)`. The two-string `r.wallets.setLabel(address,
 * label)` form is deprecated (see the `sdk-call-shape-conventions` change).
 */
import type { Client } from "../kernel.js";
export interface WalletStatusResult {
    address: string;
    created?: string;
    /**
     * True once the faucet has been invoked on this wallet. This tracks
     * "faucet has been used," not "account can pay right now" — the two diverge
     * once funds are spent or expire. Callers wanting a real pay-readiness
     * check should call `wallets balance`.
     */
    faucet_used?: boolean;
    lastFaucet?: string;
    path?: string;
    /** The persisted payment rail (`x402` when unset). */
    rail?: "x402" | "mpp" | "lightning";
    /** The Lightning wallet, without its pairing secret. */
    lightning?: {
        wallet_id: string;
        lightning_address: string | null;
        budget_sats: number;
        starter_sats: number;
        custody: "run402_hub";
        has_pairing: true;
        minted_at: string;
    };
    /** true when the local provider holds a wallet, false otherwise. */
    configured: boolean;
}
export interface WalletCreateResult {
    address: string;
    created: string;
    path?: string;
}
export interface FaucetResult {
    /** Present on gateways that wait for on-chain confirmation. */
    fundingStatus?: "confirmed";
    transactionHash: string;
    /** Display-formatted amount, e.g. `"0.25"`. Computed from `amountUsdMicros`. */
    amount: string;
    /** Raw amount in micro-USD (1_000_000 = $1.00). */
    amountUsdMicros: number;
    token: string;
    network: string;
}
export interface FaucetOptions {
    address?: string;
    idempotencyKey?: string;
}
export declare class Wallets {
    private readonly client;
    constructor(client: Client);
    /** Inspect the local wallet. Returns `{configured: false}` when absent. */
    status(): Promise<WalletStatusResult>;
    /**
     * Generate a new wallet keypair and persist it. Throws when the
     * provider already holds a wallet (don't overwrite silently) or
     * when the provider doesn't support local wallet management.
     */
    create(): Promise<WalletCreateResult>;
    /** Return the wallet address (safe to share). Throws if none is configured. */
    export(): Promise<string>;
    /**
     * Request testnet USDC from the Run402 faucet. When `address` is omitted,
     * the SDK uses the provider's local wallet address. Updates the
     * wallet's internal `funded` marker on success (surfaced as
     * `faucet_used` in `status()`).
     */
    faucet(addressOrOptions?: string | FaucetOptions): Promise<FaucetResult>;
    /**
     * Read a wallet's server-side label, or null on any error (unset, 404,
     * offline). Public read — no auth required.
     */
    getLabel(address: string): Promise<string | null>;
}
/**
 * Wallet-scoped sub-client returned by `r.wallet(address)`. Binds the address
 * so neither label method takes it as a swappable positional. Lazy — no key or
 * network access at construction.
 */
export declare class ScopedWallet {
    private readonly client;
    private readonly address;
    constructor(client: Client, address: string);
    /** Read this wallet's server-side label, or null. */
    getLabel(): Promise<string | null>;
    /** Set this wallet's server-side label. Best-effort; never throws. */
    setLabel(label: string): Promise<{
        ok: boolean;
    }>;
}
//# sourceMappingURL=wallets.d.ts.map