← Back to Viaclave

Complexity-Removal Abstractions

Seven API endpoints that replace 50+ lines of polling, parsing, and retry logic per agent. Every tool expresses domain intent and lets Viaclave do the multi-step work behind it.

GET/v1/payments/:id/wait

Wait for Payment

Long-polls a payment until it reaches a terminal state (confirmed, failed, or refunded). Removes the need for agents to implement their own polling loops with reorg handling.

Parameters

timeout(number)Max seconds to wait (1-25, default 25)

Response

{
  "status": "confirmed",
  "payment": { "id": "pay_...", "status": "confirmed", ... }
}
POST/v1/payments/verify-received

Verify Payment Received

Answers the question "did X pay me in the last hour?" without parsing signatures or scanning ledger events manually.

Parameters

from(string)Sender handle or wallet ID
amount(number)Minimum amount in micro units
since(number)Unix timestamp to search from
exact_match(boolean)Require exact amount match

Response

{
  "matched": { "id": "pay_...", "amount": 1000000, "status": "confirmed", ... }
}
POST/v1/payments/simulate

Simulate Payment

Dry-run a payment with fee calculation, balance check, and limit verification. No funds move. Removes 'will my tx fail' anxiety.

Parameters

from_wallet_id(string)Source wallet
to_wallet_id(string)Destination wallet (or to_handle/to_address)
amount(number)Amount in micro units
token(string)Token symbol (default USDC)

Response

{
  "allow": true,
  "fee_micro": 100,
  "fee_bps": 10,
  "total_debit_micro": 1000100,
  "post_balance_micro": 4999900,
  "blocking_reason": null
}
POST/v1/payments/:id/retry

Retry Payment

Idempotently retry a failed or refunded payment. Generates a new idempotency key automatically, preserving the original payment parameters.

Response

{
  "payment": { "id": "pay_new_...", "status": "pending", ... }
}
GET/v1/wallets/:id/wait-for-deposit

Wait for Deposit

Long-polls for an incoming deposit on a wallet. Useful for onboarding flows where an agent needs to wait for the user to fund their wallet.

Parameters

timeout(number)Max seconds to wait (1-25)
min_amount(number)Minimum deposit amount
since(number)Only look for deposits after this timestamp

Response

{
  "status": "deposit_found",
  "event": { "type": "credit", "amount": 5000000, ... }
}
GET/v1/wallets/:id/funding-status

Funding Status

Single-call composite health check for a wallet. Replaces 3-4 separate API calls to check balance, limits, suspension, and pause status.

Response

{
  "status": "ready",
  "details": {
    "usdc_balance": 5000000,
    "daily_spent": 100000,
    "daily_limit": 10000000,
    "is_suspended": false,
    "is_paused": false
  }
}
GET/v1/lookup?q=...

Fuzzy Lookup

Fuzzy search across your wallets, agents, and address book. Resolves handles, addresses, and aliases with Levenshtein-based scoring.

Parameters

q(string)Search query (min 2 characters)

Response

{
  "matches": [
    { "type": "agent", "id": "agt_...", "label": "payment-bot", "score": 0.9 },
    { "type": "address_book", "id": "ab_...", "label": "Alice Treasury", "score": 0.7 }
  ]
}

Address Book

Save frequently-used recipients for quick lookup via the fuzzy resolver.

POST /v1/address-bookGET /v1/address-bookPUT /v1/address-book/:idDELETE /v1/address-book/:id

SDK Usage

import { Viaclave } from "@viaclave/sdk";

const vc = new Viaclave({ apiKey: "your-key" });

// Simulate before sending
const sim = await vc.payments.simulate({
  from_wallet_id: "wal_...",
  to_handle: "merchant-bot",
  amount: 1_000_000,
});
if (!sim.allow) console.log(sim.blocking_reason);

// Send and wait
const { payment } = await vc.payments.send({ ... });
const result = await vc.payments.wait(payment.id);

// Check wallet readiness
const status = await vc.wallets.fundingStatus("wal_...");

// Fuzzy lookup
const { matches } = await vc.lookup.search("alice");