acn-client 0.6.3 → 0.8.0

package/README.md

@@ -111,8 +111,8 @@ Options:
 |--------|-------------|
 | `listSubnets()` | List all subnets |
 | `getSubnet(subnetId)` | Get subnet by ID |
-| `createSubnet(request)` | Create a new subnet |
-| `deleteSubnet(subnetId, force?)` | Delete a subnet |
+| `createSubnet(request)` | Create a new subnet (you become the owner) |
+| `deleteSubnet(subnetId)` | Delete a subnet you own |
 | `getSubnetAgents(subnetId)` | Get agents in subnet |
 | `joinSubnet(agentId, subnetId)` | Join agent to subnet |
 | `leaveSubnet(agentId, subnetId)` | Remove agent from subnet |
@@ -146,13 +146,28 @@ Options:
 
 | Method | Description |
 |--------|-------------|
-| `discoverPaymentAgents(options?)` | Find agents accepting payments |
+| `discoverPaymentAgents({ method?, network? })` | Find agents accepting payments (lowercase enum values) |
 | `getPaymentCapability(agentId)` | Get agent's payment capability |
-| `setPaymentCapability(agentId, capability)` | Set payment capability |
-| `getPaymentTask(taskId)` | Get payment task |
-| `getAgentPaymentTasks(agentId, options?)` | Get agent's payment tasks |
+| `setPaymentCapability(agentId, capability)` | Set accepted methods/networks/wallets |
+| `getTokenPricing(agentId)` | Get an agent's per-million-token pricing |
+| `setTokenPricing(agentId, { input_price_per_million, output_price_per_million })` | Set OpenAI-style per-million-token pricing (USD) |
+| `createPaymentTask({ from_agent, to_agent, amount, currency, payment_method, network, ... })` | Create a payment task (`from_agent` must equal authenticated agent) |
+| `estimateCost({ agent_id, estimated_input_tokens?, estimated_output_tokens? })` | Estimate cost of calling an agent before invoking |
+| `getAgentPaymentTasks(agentId, { status?, limit? })` | List the payment tasks the agent is involved in |
+| `getPaymentTask(taskId)` | Get a payment task (server requires internal token) |
 | `getPaymentStats(agentId)` | Get payment statistics |
 
+> **Migration from 0.6.x → 0.7.0** — `PaymentMethod` and `PaymentNetwork`
+> are now lowercase string-literal unions (e.g. `'usdc'`, `'base'`),
+> aligning with the ACN server. Update any literal comparisons
+> accordingly. `PaymentTask.status` is now `string`; use the new
+> `KNOWN_PAYMENT_TASK_STATUSES` constant for known values.
+> `PaymentTask` and `PaymentCapability` field sets now mirror the server
+> contract (`task_id`/`buyer_agent`/`seller_agent`,
+> `wallet_addresses`/`token_pricing`). `PaymentDiscoveryOptions` no
+> longer accepts `min_amount` / `max_amount` (the server never read
+> them).
+
 #### Monitoring Methods
 
 | Method | Description |

package/dist/index.d.mts

@@ -329,50 +329,100 @@ interface PendingSessionsResponse {
     count: number;
     sessions: SessionEntry[];
 }
-/** Supported payment methods */
-type PaymentMethod = 'USDC' | 'USDT' | 'ETH' | 'DAI' | 'CREDIT_CARD' | 'BANK_TRANSFER' | 'PLATFORM_CREDITS';
-/** Supported networks */
-type PaymentNetwork = 'ETHEREUM' | 'POLYGON' | 'BASE' | 'ARBITRUM' | 'OPTIMISM' | 'SOLANA';
-/** Payment capability */
+/**
+ * Supported payment methods.
+ *
+ * Values aligned with ACN server `SupportedPaymentMethod` (lowercase).
+ */
+type PaymentMethod = 'credit_card' | 'debit_card' | 'bank_transfer' | 'paypal' | 'apple_pay' | 'google_pay' | 'usdc' | 'usdt' | 'dai' | 'eth' | 'btc' | 'platform_credits';
+/**
+ * Supported networks.
+ *
+ * Values aligned with ACN server `SupportedNetwork` (lowercase).
+ */
+type PaymentNetwork = 'ethereum' | 'base' | 'arbitrum' | 'optimism' | 'polygon' | 'solana' | 'bitcoin';
+/**
+ * Payment capability — aligned with ACN `PaymentCapabilityRequest`.
+ *
+ * Used both as the body for `setPaymentCapability` and the response
+ * shape of `getPaymentCapability`.
+ */
 interface PaymentCapability {
-    accepts_payment: boolean;
-    wallet_address?: string;
     supported_methods: PaymentMethod[];
     supported_networks: PaymentNetwork[];
-    min_amount?: number;
-    max_amount?: number;
-    currency?: string;
+    /** Legacy single-address field; prefer `wallet_addresses`. */
+    wallet_address?: string;
+    /** Per-network wallet addresses, e.g. `{ ethereum: '0x...', base: '0x...' }`. */
+    wallet_addresses?: Record<string, string>;
+    accepts_payment?: boolean;
+    /**
+     * Token-based pricing payload, e.g.
+     * `{ input_price_per_million: 2.5, output_price_per_million: 10.0, currency: 'USD' }`.
+     */
+    token_pricing?: Record<string, unknown> | null;
+    api_endpoint?: string;
+    webhook_url?: string;
 }
-/** Payment task status */
-type PaymentTaskStatus = 'pending' | 'in_progress' | 'completed' | 'failed' | 'cancelled';
-/** Payment task */
+/**
+ * Known ACN payment task status values.
+ *
+ * `PaymentTask.status` is typed as `string` rather than this union so the
+ * SDK does not need a release whenever the server adds a state. Compare
+ * against these constants when branching on status.
+ */
+declare const KNOWN_PAYMENT_TASK_STATUSES: readonly ["created", "payment_requested", "payment_pending", "payment_confirmed", "task_in_progress", "task_completed", "payment_released", "in_progress", "disputed", "cancelled", "failed", "payment_failed", "refunded"];
+type PaymentTaskStatus = (typeof KNOWN_PAYMENT_TASK_STATUSES)[number];
+/** Payment task — aligned with ACN server `PaymentTask` (ap2.core). */
 interface PaymentTask {
-    id: string;
-    payer_agent_id: string;
-    payee_agent_id: string;
-    amount: number;
-    currency: string;
-    method: PaymentMethod;
-    network?: PaymentNetwork;
-    status: PaymentTaskStatus;
+    task_id: string;
+    payment_id?: string | null;
+    buyer_agent: string;
+    seller_agent: string;
+    task_description: string;
+    task_type?: string | null;
+    task_metadata?: Record<string, unknown>;
+    /** Decimal amount as a string (matches server contract). */
+    amount: string;
+    currency?: string;
+    payment_method?: PaymentMethod | null;
+    network?: PaymentNetwork | null;
+    recipient_wallet?: string | null;
+    /** A `KNOWN_PAYMENT_TASK_STATUSES` value, but typed wide for forward-compat. */
+    status: string;
     created_at: string;
-    updated_at: string;
-    transaction_hash?: string;
-    metadata?: Record<string, unknown>;
+    payment_requested_at?: string | null;
+    payment_confirmed_at?: string | null;
+    task_completed_at?: string | null;
+    payment_released_at?: string | null;
+    tx_hash?: string | null;
+    dispute?: Record<string, unknown> | null;
 }
-/** Payment discovery options */
+/** Payment discovery options. */
 interface PaymentDiscoveryOptions {
     method?: PaymentMethod;
     network?: PaymentNetwork;
-    min_amount?: number;
-    max_amount?: number;
 }
-/** Payment statistics */
+/**
+ * Per-role aggregate within {@link PaymentStats} (`as_buyer` / `as_seller`).
+ *
+ * `total_amount` is a decimal string (matches server contract).
+ */
+interface PaymentRoleStats {
+    count: number;
+    total_amount: string;
+}
+/**
+ * Payment statistics — aligned with `PaymentTaskManager.get_payment_stats`.
+ *
+ * The server aggregates per-status counts plus per-role (buyer/seller)
+ * totals as decimal strings, rather than flat received/sent floats.
+ */
 interface PaymentStats {
-    total_received: number;
-    total_sent: number;
-    transaction_count: number;
-    avg_amount: number;
+    total_tasks: number;
+    as_buyer: PaymentRoleStats;
+    as_seller: PaymentRoleStats;
+    by_status: Record<string, number>;
+    completed_transactions: number;
 }
 /** System health */
 interface SystemHealth {
@@ -632,8 +682,8 @@ declare class ACNClient {
     }>;
     /** Get subnet by ID */
     getSubnet(subnetId: string): Promise<SubnetInfo>;
-    /** Delete a subnet */
-    deleteSubnet(subnetId: string, force?: boolean): Promise<{
+    /** Delete a subnet you own (requires Agent API Key — only the owning agent can delete) */
+    deleteSubnet(subnetId: string): Promise<{
         success: boolean;
     }>;
     /** Get agents in a subnet */
@@ -835,27 +885,96 @@ declare class ACNClient {
      * after fetchManifestContent.
      */
     deleteManifest(agentId: string, mid: string): Promise<Record<string, unknown>>;
-    /** Set agent's payment capability */
+    /** Set agent's payment capability (requires Agent API Key) */
     setPaymentCapability(agentId: string, capability: PaymentCapability): Promise<{
         success: boolean;
     }>;
-    /** Get agent's payment capability */
+    /**
+     * Get agent's payment capability (requires Agent API Key).
+     *
+     * The ACN server returns this resource using the internal
+     * `ap2.core.PaymentCapability` shape, which calls the methods list
+     * `payment_methods`.  We rewrite it to the request-shaped name
+     * `supported_methods` here so callers see the same field on read
+     * and on write.
+     */
     getPaymentCapability(agentId: string): Promise<PaymentCapability | null>;
-    /** Discover agents that accept payments */
+    /** Set OpenAI-style per-million-token pricing in USD (requires Agent API Key) */
+    setTokenPricing(agentId: string, pricing: {
+        input_price_per_million: number;
+        output_price_per_million: number;
+    }): Promise<{
+        status: string;
+        agent_id: string;
+        token_pricing: {
+            input_price_per_million: number;
+            output_price_per_million: number;
+            currency: string;
+        };
+        network_fee_rate?: number;
+    }>;
+    /** Get an agent's per-million-token pricing (requires Agent API Key) */
+    getTokenPricing(agentId: string): Promise<{
+        input_price_per_million: number;
+        output_price_per_million: number;
+        currency: string;
+    } | null>;
+    /** Discover agents that accept payments. Filters by lowercase method/network. */
     discoverPaymentAgents(options?: PaymentDiscoveryOptions): Promise<{
         agents: AgentInfo[];
     }>;
-    /** Get payment task by ID */
+    /**
+     * Create a payment task (requires Agent API Key).
+     *
+     * `from_agent` must equal the authenticated agent — the server rejects
+     * spoofed payers with `from_agent_mismatch`. `payment_method` and
+     * `network` use ACN lowercase values (e.g. `'usdc'`, `'base'`).
+     */
+    createPaymentTask(request: {
+        from_agent: string;
+        to_agent: string;
+        amount: number;
+        currency: string;
+        payment_method: PaymentMethod;
+        network: PaymentNetwork;
+        description?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<{
+        task_id: string;
+        status: string;
+    }>;
+    /**
+     * Estimate the cost of calling an agent before invoking its service.
+     *
+     * Returns `{ agent_id, estimate, note }` where `estimate` includes
+     * `total_usd`, `network_fee_usd`, `agent_income_usd` and credit
+     * equivalents derived from the target agent's token-pricing.
+     */
+    estimateCost(request: {
+        agent_id: string;
+        estimated_input_tokens?: number;
+        estimated_output_tokens?: number;
+    }): Promise<{
+        agent_id: string;
+        estimate: Record<string, number>;
+        note?: string;
+    }>;
+    /**
+     * Get a payment task by ID.
+     *
+     * Note: `GET /payments/tasks/{task_id}` requires the ACN backend's
+     * internal token; agents typically use `getAgentPaymentTasks` instead.
+     */
     getPaymentTask(taskId: string): Promise<PaymentTask>;
-    /** Get agent's payment tasks */
+    /** Get the payment tasks an agent is involved in (requires Agent API Key). */
     getAgentPaymentTasks(agentId: string, options?: {
-        role?: 'payer' | 'payee';
         status?: string;
         limit?: number;
     }): Promise<{
+        agent_id: string;
         tasks: PaymentTask[];
     }>;
-    /** Get agent's payment statistics */
+    /** Get an agent's payment statistics (requires Agent API Key). */
     getPaymentStats(agentId: string): Promise<PaymentStats>;
     /** Get Prometheus metrics (text format) */
     getPrometheusMetrics(): Promise<string>;
@@ -1106,4 +1225,4 @@ declare class ACNRealtime {
  */
 declare function subscribeToACN<T = unknown>(baseUrl: string, channel: string, handler: WSEventHandler<T>): () => void;
 
-export { ACNClient, type ACNClientOptions, ACNError, ACNRealtime, type ActivityEntry, type AgentActivity, type AgentAnalytics, type AgentInfo, type AgentJoinRequest, type AgentJoinResponse, type AgentRegisterRequest, type AgentRegisterResponse, type AgentSearchOptions, type AgentSearchResponse, type AgentStatus, type AllowlistActionResponse, type AllowlistEntry, type AllowlistListResponse, type ApiResponse, type AttentionFee, type AuditEvent, type AuditQueryOptions, type BroadcastBySkillRequest, type BroadcastByTagRequest, type BroadcastRequest, type BroadcastStrategy, type CommunicationPolicyMode, type CommunicationPolicyResponse, type ComponentHealth, type DashboardData, type FollowActionResponse, type FollowCheckResponse, type ManifestContentResponse, type ManifestEntry, type ManifestListResponse, type Message, type MessageType, type MetricsData, type PaymentCapability, type PaymentDiscoveryOptions, type PaymentMethod, type PaymentNetwork, type PaymentStats, type PaymentTask, type PaymentTaskStatus, type SendMessageRequest, type SendMessageResponse, type SubnetCreateRequest, type SubnetCreateResponse, type SubnetInfo, type SystemHealth, type WSConnectionOptions, type WSEventHandler, type WSEventType, type WSMessage, type WSState, subscribeToACN };
+export { ACNClient, type ACNClientOptions, ACNError, ACNRealtime, type ActivityEntry, type AgentActivity, type AgentAnalytics, type AgentInfo, type AgentJoinRequest, type AgentJoinResponse, type AgentRegisterRequest, type AgentRegisterResponse, type AgentSearchOptions, type AgentSearchResponse, type AgentStatus, type AllowlistActionResponse, type AllowlistEntry, type AllowlistListResponse, type ApiResponse, type AttentionFee, type AuditEvent, type AuditQueryOptions, type BroadcastBySkillRequest, type BroadcastByTagRequest, type BroadcastRequest, type BroadcastStrategy, type CommunicationPolicyMode, type CommunicationPolicyResponse, type ComponentHealth, type DashboardData, type FollowActionResponse, type FollowCheckResponse, KNOWN_PAYMENT_TASK_STATUSES, type ManifestContentResponse, type ManifestEntry, type ManifestListResponse, type Message, type MessageType, type MetricsData, type PaymentCapability, type PaymentDiscoveryOptions, type PaymentMethod, type PaymentNetwork, type PaymentRoleStats, type PaymentStats, type PaymentTask, type PaymentTaskStatus, type SendMessageRequest, type SendMessageResponse, type SubnetCreateRequest, type SubnetCreateResponse, type SubnetInfo, type SystemHealth, type WSConnectionOptions, type WSEventHandler, type WSEventType, type WSMessage, type WSState, subscribeToACN };

package/dist/index.d.ts

@@ -329,50 +329,100 @@ interface PendingSessionsResponse {
     count: number;
     sessions: SessionEntry[];
 }
-/** Supported payment methods */
-type PaymentMethod = 'USDC' | 'USDT' | 'ETH' | 'DAI' | 'CREDIT_CARD' | 'BANK_TRANSFER' | 'PLATFORM_CREDITS';
-/** Supported networks */
-type PaymentNetwork = 'ETHEREUM' | 'POLYGON' | 'BASE' | 'ARBITRUM' | 'OPTIMISM' | 'SOLANA';
-/** Payment capability */
+/**
+ * Supported payment methods.
+ *
+ * Values aligned with ACN server `SupportedPaymentMethod` (lowercase).
+ */
+type PaymentMethod = 'credit_card' | 'debit_card' | 'bank_transfer' | 'paypal' | 'apple_pay' | 'google_pay' | 'usdc' | 'usdt' | 'dai' | 'eth' | 'btc' | 'platform_credits';
+/**
+ * Supported networks.
+ *
+ * Values aligned with ACN server `SupportedNetwork` (lowercase).
+ */
+type PaymentNetwork = 'ethereum' | 'base' | 'arbitrum' | 'optimism' | 'polygon' | 'solana' | 'bitcoin';
+/**
+ * Payment capability — aligned with ACN `PaymentCapabilityRequest`.
+ *
+ * Used both as the body for `setPaymentCapability` and the response
+ * shape of `getPaymentCapability`.
+ */
 interface PaymentCapability {
-    accepts_payment: boolean;
-    wallet_address?: string;
     supported_methods: PaymentMethod[];
     supported_networks: PaymentNetwork[];
-    min_amount?: number;
-    max_amount?: number;
-    currency?: string;
+    /** Legacy single-address field; prefer `wallet_addresses`. */
+    wallet_address?: string;
+    /** Per-network wallet addresses, e.g. `{ ethereum: '0x...', base: '0x...' }`. */
+    wallet_addresses?: Record<string, string>;
+    accepts_payment?: boolean;
+    /**
+     * Token-based pricing payload, e.g.
+     * `{ input_price_per_million: 2.5, output_price_per_million: 10.0, currency: 'USD' }`.
+     */
+    token_pricing?: Record<string, unknown> | null;
+    api_endpoint?: string;
+    webhook_url?: string;
 }
-/** Payment task status */
-type PaymentTaskStatus = 'pending' | 'in_progress' | 'completed' | 'failed' | 'cancelled';
-/** Payment task */
+/**
+ * Known ACN payment task status values.
+ *
+ * `PaymentTask.status` is typed as `string` rather than this union so the
+ * SDK does not need a release whenever the server adds a state. Compare
+ * against these constants when branching on status.
+ */
+declare const KNOWN_PAYMENT_TASK_STATUSES: readonly ["created", "payment_requested", "payment_pending", "payment_confirmed", "task_in_progress", "task_completed", "payment_released", "in_progress", "disputed", "cancelled", "failed", "payment_failed", "refunded"];
+type PaymentTaskStatus = (typeof KNOWN_PAYMENT_TASK_STATUSES)[number];
+/** Payment task — aligned with ACN server `PaymentTask` (ap2.core). */
 interface PaymentTask {
-    id: string;
-    payer_agent_id: string;
-    payee_agent_id: string;
-    amount: number;
-    currency: string;
-    method: PaymentMethod;
-    network?: PaymentNetwork;
-    status: PaymentTaskStatus;
+    task_id: string;
+    payment_id?: string | null;
+    buyer_agent: string;
+    seller_agent: string;
+    task_description: string;
+    task_type?: string | null;
+    task_metadata?: Record<string, unknown>;
+    /** Decimal amount as a string (matches server contract). */
+    amount: string;
+    currency?: string;
+    payment_method?: PaymentMethod | null;
+    network?: PaymentNetwork | null;
+    recipient_wallet?: string | null;
+    /** A `KNOWN_PAYMENT_TASK_STATUSES` value, but typed wide for forward-compat. */
+    status: string;
     created_at: string;
-    updated_at: string;
-    transaction_hash?: string;
-    metadata?: Record<string, unknown>;
+    payment_requested_at?: string | null;
+    payment_confirmed_at?: string | null;
+    task_completed_at?: string | null;
+    payment_released_at?: string | null;
+    tx_hash?: string | null;
+    dispute?: Record<string, unknown> | null;
 }
-/** Payment discovery options */
+/** Payment discovery options. */
 interface PaymentDiscoveryOptions {
     method?: PaymentMethod;
     network?: PaymentNetwork;
-    min_amount?: number;
-    max_amount?: number;
 }
-/** Payment statistics */
+/**
+ * Per-role aggregate within {@link PaymentStats} (`as_buyer` / `as_seller`).
+ *
+ * `total_amount` is a decimal string (matches server contract).
+ */
+interface PaymentRoleStats {
+    count: number;
+    total_amount: string;
+}
+/**
+ * Payment statistics — aligned with `PaymentTaskManager.get_payment_stats`.
+ *
+ * The server aggregates per-status counts plus per-role (buyer/seller)
+ * totals as decimal strings, rather than flat received/sent floats.
+ */
 interface PaymentStats {
-    total_received: number;
-    total_sent: number;
-    transaction_count: number;
-    avg_amount: number;
+    total_tasks: number;
+    as_buyer: PaymentRoleStats;
+    as_seller: PaymentRoleStats;
+    by_status: Record<string, number>;
+    completed_transactions: number;
 }
 /** System health */
 interface SystemHealth {
@@ -632,8 +682,8 @@ declare class ACNClient {
     }>;
     /** Get subnet by ID */
     getSubnet(subnetId: string): Promise<SubnetInfo>;
-    /** Delete a subnet */
-    deleteSubnet(subnetId: string, force?: boolean): Promise<{
+    /** Delete a subnet you own (requires Agent API Key — only the owning agent can delete) */
+    deleteSubnet(subnetId: string): Promise<{
         success: boolean;
     }>;
     /** Get agents in a subnet */
@@ -835,27 +885,96 @@ declare class ACNClient {
      * after fetchManifestContent.
      */
     deleteManifest(agentId: string, mid: string): Promise<Record<string, unknown>>;
-    /** Set agent's payment capability */
+    /** Set agent's payment capability (requires Agent API Key) */
     setPaymentCapability(agentId: string, capability: PaymentCapability): Promise<{
         success: boolean;
     }>;
-    /** Get agent's payment capability */
+    /**
+     * Get agent's payment capability (requires Agent API Key).
+     *
+     * The ACN server returns this resource using the internal
+     * `ap2.core.PaymentCapability` shape, which calls the methods list
+     * `payment_methods`.  We rewrite it to the request-shaped name
+     * `supported_methods` here so callers see the same field on read
+     * and on write.
+     */
     getPaymentCapability(agentId: string): Promise<PaymentCapability | null>;
-    /** Discover agents that accept payments */
+    /** Set OpenAI-style per-million-token pricing in USD (requires Agent API Key) */
+    setTokenPricing(agentId: string, pricing: {
+        input_price_per_million: number;
+        output_price_per_million: number;
+    }): Promise<{
+        status: string;
+        agent_id: string;
+        token_pricing: {
+            input_price_per_million: number;
+            output_price_per_million: number;
+            currency: string;
+        };
+        network_fee_rate?: number;
+    }>;
+    /** Get an agent's per-million-token pricing (requires Agent API Key) */
+    getTokenPricing(agentId: string): Promise<{
+        input_price_per_million: number;
+        output_price_per_million: number;
+        currency: string;
+    } | null>;
+    /** Discover agents that accept payments. Filters by lowercase method/network. */
     discoverPaymentAgents(options?: PaymentDiscoveryOptions): Promise<{
         agents: AgentInfo[];
     }>;
-    /** Get payment task by ID */
+    /**
+     * Create a payment task (requires Agent API Key).
+     *
+     * `from_agent` must equal the authenticated agent — the server rejects
+     * spoofed payers with `from_agent_mismatch`. `payment_method` and
+     * `network` use ACN lowercase values (e.g. `'usdc'`, `'base'`).
+     */
+    createPaymentTask(request: {
+        from_agent: string;
+        to_agent: string;
+        amount: number;
+        currency: string;
+        payment_method: PaymentMethod;
+        network: PaymentNetwork;
+        description?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<{
+        task_id: string;
+        status: string;
+    }>;
+    /**
+     * Estimate the cost of calling an agent before invoking its service.
+     *
+     * Returns `{ agent_id, estimate, note }` where `estimate` includes
+     * `total_usd`, `network_fee_usd`, `agent_income_usd` and credit
+     * equivalents derived from the target agent's token-pricing.
+     */
+    estimateCost(request: {
+        agent_id: string;
+        estimated_input_tokens?: number;
+        estimated_output_tokens?: number;
+    }): Promise<{
+        agent_id: string;
+        estimate: Record<string, number>;
+        note?: string;
+    }>;
+    /**
+     * Get a payment task by ID.
+     *
+     * Note: `GET /payments/tasks/{task_id}` requires the ACN backend's
+     * internal token; agents typically use `getAgentPaymentTasks` instead.
+     */
     getPaymentTask(taskId: string): Promise<PaymentTask>;
-    /** Get agent's payment tasks */
+    /** Get the payment tasks an agent is involved in (requires Agent API Key). */
     getAgentPaymentTasks(agentId: string, options?: {
-        role?: 'payer' | 'payee';
         status?: string;
         limit?: number;
     }): Promise<{
+        agent_id: string;
         tasks: PaymentTask[];
     }>;
-    /** Get agent's payment statistics */
+    /** Get an agent's payment statistics (requires Agent API Key). */
     getPaymentStats(agentId: string): Promise<PaymentStats>;
     /** Get Prometheus metrics (text format) */
     getPrometheusMetrics(): Promise<string>;
@@ -1106,4 +1225,4 @@ declare class ACNRealtime {
  */
 declare function subscribeToACN<T = unknown>(baseUrl: string, channel: string, handler: WSEventHandler<T>): () => void;
 
-export { ACNClient, type ACNClientOptions, ACNError, ACNRealtime, type ActivityEntry, type AgentActivity, type AgentAnalytics, type AgentInfo, type AgentJoinRequest, type AgentJoinResponse, type AgentRegisterRequest, type AgentRegisterResponse, type AgentSearchOptions, type AgentSearchResponse, type AgentStatus, type AllowlistActionResponse, type AllowlistEntry, type AllowlistListResponse, type ApiResponse, type AttentionFee, type AuditEvent, type AuditQueryOptions, type BroadcastBySkillRequest, type BroadcastByTagRequest, type BroadcastRequest, type BroadcastStrategy, type CommunicationPolicyMode, type CommunicationPolicyResponse, type ComponentHealth, type DashboardData, type FollowActionResponse, type FollowCheckResponse, type ManifestContentResponse, type ManifestEntry, type ManifestListResponse, type Message, type MessageType, type MetricsData, type PaymentCapability, type PaymentDiscoveryOptions, type PaymentMethod, type PaymentNetwork, type PaymentStats, type PaymentTask, type PaymentTaskStatus, type SendMessageRequest, type SendMessageResponse, type SubnetCreateRequest, type SubnetCreateResponse, type SubnetInfo, type SystemHealth, type WSConnectionOptions, type WSEventHandler, type WSEventType, type WSMessage, type WSState, subscribeToACN };
+export { ACNClient, type ACNClientOptions, ACNError, ACNRealtime, type ActivityEntry, type AgentActivity, type AgentAnalytics, type AgentInfo, type AgentJoinRequest, type AgentJoinResponse, type AgentRegisterRequest, type AgentRegisterResponse, type AgentSearchOptions, type AgentSearchResponse, type AgentStatus, type AllowlistActionResponse, type AllowlistEntry, type AllowlistListResponse, type ApiResponse, type AttentionFee, type AuditEvent, type AuditQueryOptions, type BroadcastBySkillRequest, type BroadcastByTagRequest, type BroadcastRequest, type BroadcastStrategy, type CommunicationPolicyMode, type CommunicationPolicyResponse, type ComponentHealth, type DashboardData, type FollowActionResponse, type FollowCheckResponse, KNOWN_PAYMENT_TASK_STATUSES, type ManifestContentResponse, type ManifestEntry, type ManifestListResponse, type Message, type MessageType, type MetricsData, type PaymentCapability, type PaymentDiscoveryOptions, type PaymentMethod, type PaymentNetwork, type PaymentRoleStats, type PaymentStats, type PaymentTask, type PaymentTaskStatus, type SendMessageRequest, type SendMessageResponse, type SubnetCreateRequest, type SubnetCreateResponse, type SubnetInfo, type SystemHealth, type WSConnectionOptions, type WSEventHandler, type WSEventType, type WSMessage, type WSState, subscribeToACN };

package/dist/index.js

@@ -33,6 +33,7 @@ __export(index_exports, {
   ACNClient: () => ACNClient,
   ACNError: () => ACNError,
   ACNRealtime: () => ACNRealtime,
+  KNOWN_PAYMENT_TASK_STATUSES: () => KNOWN_PAYMENT_TASK_STATUSES,
   subscribeToACN: () => subscribeToACN
 });
 module.exports = __toCommonJS(index_exports);
@@ -209,11 +210,9 @@ var ACNClient = class {
   async getSubnet(subnetId) {
     return this.get(`/api/v1/subnets/${subnetId}`);
   }
-  /** Delete a subnet */
-  async deleteSubnet(subnetId, force = false) {
-    return this.request("DELETE", `/api/v1/subnets/${subnetId}`, {
-      params: { force }
-    });
+  /** Delete a subnet you own (requires Agent API Key — only the owning agent can delete) */
+  async deleteSubnet(subnetId) {
+    return this.request("DELETE", `/api/v1/subnets/${subnetId}`);
   }
   /** Get agents in a subnet */
   async getSubnetAgents(subnetId) {
@@ -437,32 +436,82 @@ var ACNClient = class {
   // ============================================
   // Payment Discovery
   // ============================================
-  /** Set agent's payment capability */
+  /** Set agent's payment capability (requires Agent API Key) */
   async setPaymentCapability(agentId, capability) {
-    return this.post(`/api/v1/agents/${agentId}/payment-capability`, capability);
+    return this.post(`/api/v1/payments/${agentId}/payment-capability`, capability);
   }
-  /** Get agent's payment capability */
+  /**
+   * Get agent's payment capability (requires Agent API Key).
+   *
+   * The ACN server returns this resource using the internal
+   * `ap2.core.PaymentCapability` shape, which calls the methods list
+   * `payment_methods`.  We rewrite it to the request-shaped name
+   * `supported_methods` here so callers see the same field on read
+   * and on write.
+   */
   async getPaymentCapability(agentId) {
-    return this.get(`/api/v1/agents/${agentId}/payment-capability`);
+    const raw = await this.get(
+      `/api/v1/payments/${agentId}/payment-capability`
+    );
+    if (!raw) return null;
+    if (Array.isArray(raw.payment_methods) && raw.supported_methods === void 0) {
+      raw.supported_methods = raw.payment_methods;
+    }
+    return raw;
   }
-  /** Discover agents that accept payments */
+  /** Set OpenAI-style per-million-token pricing in USD (requires Agent API Key) */
+  async setTokenPricing(agentId, pricing) {
+    return this.post(`/api/v1/payments/${agentId}/token-pricing`, pricing);
+  }
+  /** Get an agent's per-million-token pricing (requires Agent API Key) */
+  async getTokenPricing(agentId) {
+    return this.get(`/api/v1/payments/${agentId}/token-pricing`);
+  }
+  /** Discover agents that accept payments. Filters by lowercase method/network. */
   async discoverPaymentAgents(options) {
     return this.get("/api/v1/payments/discover", {
       method: options?.method,
-      network: options?.network,
-      min_amount: options?.min_amount,
-      max_amount: options?.max_amount
+      network: options?.network
     });
   }
-  /** Get payment task by ID */
+  /**
+   * Create a payment task (requires Agent API Key).
+   *
+   * `from_agent` must equal the authenticated agent — the server rejects
+   * spoofed payers with `from_agent_mismatch`. `payment_method` and
+   * `network` use ACN lowercase values (e.g. `'usdc'`, `'base'`).
+   */
+  async createPaymentTask(request) {
+    return this.post("/api/v1/payments/tasks", request);
+  }
+  /**
+   * Estimate the cost of calling an agent before invoking its service.
+   *
+   * Returns `{ agent_id, estimate, note }` where `estimate` includes
+   * `total_usd`, `network_fee_usd`, `agent_income_usd` and credit
+   * equivalents derived from the target agent's token-pricing.
+   */
+  async estimateCost(request) {
+    return this.post("/api/v1/payments/billing/estimate", {
+      agent_id: request.agent_id,
+      estimated_input_tokens: request.estimated_input_tokens ?? 0,
+      estimated_output_tokens: request.estimated_output_tokens ?? 0
+    });
+  }
+  /**
+   * Get a payment task by ID.
+   *
+   * Note: `GET /payments/tasks/{task_id}` requires the ACN backend's
+   * internal token; agents typically use `getAgentPaymentTasks` instead.
+   */
   async getPaymentTask(taskId) {
     return this.get(`/api/v1/payments/tasks/${taskId}`);
   }
-  /** Get agent's payment tasks */
+  /** Get the payment tasks an agent is involved in (requires Agent API Key). */
   async getAgentPaymentTasks(agentId, options) {
     return this.get(`/api/v1/payments/tasks/agent/${agentId}`, options);
   }
-  /** Get agent's payment statistics */
+  /** Get an agent's payment statistics (requires Agent API Key). */
   async getPaymentStats(agentId) {
     return this.get(`/api/v1/payments/stats/${agentId}`);
   }
@@ -953,10 +1002,28 @@ function subscribeToACN(baseUrl, channel, handler) {
     realtime.disconnect();
   };
 }
+
+// src/types.ts
+var KNOWN_PAYMENT_TASK_STATUSES = [
+  "created",
+  "payment_requested",
+  "payment_pending",
+  "payment_confirmed",
+  "task_in_progress",
+  "task_completed",
+  "payment_released",
+  "in_progress",
+  "disputed",
+  "cancelled",
+  "failed",
+  "payment_failed",
+  "refunded"
+];
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ACNClient,
   ACNError,
   ACNRealtime,
+  KNOWN_PAYMENT_TASK_STATUSES,
   subscribeToACN
 });

package/dist/index.mjs

@@ -170,11 +170,9 @@ var ACNClient = class {
   async getSubnet(subnetId) {
     return this.get(`/api/v1/subnets/${subnetId}`);
   }
-  /** Delete a subnet */
-  async deleteSubnet(subnetId, force = false) {
-    return this.request("DELETE", `/api/v1/subnets/${subnetId}`, {
-      params: { force }
-    });
+  /** Delete a subnet you own (requires Agent API Key — only the owning agent can delete) */
+  async deleteSubnet(subnetId) {
+    return this.request("DELETE", `/api/v1/subnets/${subnetId}`);
   }
   /** Get agents in a subnet */
   async getSubnetAgents(subnetId) {
@@ -398,32 +396,82 @@ var ACNClient = class {
   // ============================================
   // Payment Discovery
   // ============================================
-  /** Set agent's payment capability */
+  /** Set agent's payment capability (requires Agent API Key) */
   async setPaymentCapability(agentId, capability) {
-    return this.post(`/api/v1/agents/${agentId}/payment-capability`, capability);
+    return this.post(`/api/v1/payments/${agentId}/payment-capability`, capability);
   }
-  /** Get agent's payment capability */
+  /**
+   * Get agent's payment capability (requires Agent API Key).
+   *
+   * The ACN server returns this resource using the internal
+   * `ap2.core.PaymentCapability` shape, which calls the methods list
+   * `payment_methods`.  We rewrite it to the request-shaped name
+   * `supported_methods` here so callers see the same field on read
+   * and on write.
+   */
   async getPaymentCapability(agentId) {
-    return this.get(`/api/v1/agents/${agentId}/payment-capability`);
+    const raw = await this.get(
+      `/api/v1/payments/${agentId}/payment-capability`
+    );
+    if (!raw) return null;
+    if (Array.isArray(raw.payment_methods) && raw.supported_methods === void 0) {
+      raw.supported_methods = raw.payment_methods;
+    }
+    return raw;
   }
-  /** Discover agents that accept payments */
+  /** Set OpenAI-style per-million-token pricing in USD (requires Agent API Key) */
+  async setTokenPricing(agentId, pricing) {
+    return this.post(`/api/v1/payments/${agentId}/token-pricing`, pricing);
+  }
+  /** Get an agent's per-million-token pricing (requires Agent API Key) */
+  async getTokenPricing(agentId) {
+    return this.get(`/api/v1/payments/${agentId}/token-pricing`);
+  }
+  /** Discover agents that accept payments. Filters by lowercase method/network. */
   async discoverPaymentAgents(options) {
     return this.get("/api/v1/payments/discover", {
       method: options?.method,
-      network: options?.network,
-      min_amount: options?.min_amount,
-      max_amount: options?.max_amount
+      network: options?.network
     });
   }
-  /** Get payment task by ID */
+  /**
+   * Create a payment task (requires Agent API Key).
+   *
+   * `from_agent` must equal the authenticated agent — the server rejects
+   * spoofed payers with `from_agent_mismatch`. `payment_method` and
+   * `network` use ACN lowercase values (e.g. `'usdc'`, `'base'`).
+   */
+  async createPaymentTask(request) {
+    return this.post("/api/v1/payments/tasks", request);
+  }
+  /**
+   * Estimate the cost of calling an agent before invoking its service.
+   *
+   * Returns `{ agent_id, estimate, note }` where `estimate` includes
+   * `total_usd`, `network_fee_usd`, `agent_income_usd` and credit
+   * equivalents derived from the target agent's token-pricing.
+   */
+  async estimateCost(request) {
+    return this.post("/api/v1/payments/billing/estimate", {
+      agent_id: request.agent_id,
+      estimated_input_tokens: request.estimated_input_tokens ?? 0,
+      estimated_output_tokens: request.estimated_output_tokens ?? 0
+    });
+  }
+  /**
+   * Get a payment task by ID.
+   *
+   * Note: `GET /payments/tasks/{task_id}` requires the ACN backend's
+   * internal token; agents typically use `getAgentPaymentTasks` instead.
+   */
   async getPaymentTask(taskId) {
     return this.get(`/api/v1/payments/tasks/${taskId}`);
   }
-  /** Get agent's payment tasks */
+  /** Get the payment tasks an agent is involved in (requires Agent API Key). */
   async getAgentPaymentTasks(agentId, options) {
     return this.get(`/api/v1/payments/tasks/agent/${agentId}`, options);
   }
-  /** Get agent's payment statistics */
+  /** Get an agent's payment statistics (requires Agent API Key). */
   async getPaymentStats(agentId) {
     return this.get(`/api/v1/payments/stats/${agentId}`);
   }
@@ -914,9 +962,27 @@ function subscribeToACN(baseUrl, channel, handler) {
     realtime.disconnect();
   };
 }
+
+// src/types.ts
+var KNOWN_PAYMENT_TASK_STATUSES = [
+  "created",
+  "payment_requested",
+  "payment_pending",
+  "payment_confirmed",
+  "task_in_progress",
+  "task_completed",
+  "payment_released",
+  "in_progress",
+  "disputed",
+  "cancelled",
+  "failed",
+  "payment_failed",
+  "refunded"
+];
 export {
   ACNClient,
   ACNError,
   ACNRealtime,
+  KNOWN_PAYMENT_TASK_STATUSES,
   subscribeToACN
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acn-client",
-  "version": "0.6.3",
+  "version": "0.8.0",
   "description": "Official TypeScript/JavaScript client for ACN (Agent Collaboration Network)",
   "main": "dist/index.js",
   "module": "dist/index.mjs",