> ## Documentation Index > Fetch the complete documentation index at: https://docs.sumvin.com/llms.txt > Use this file to discover all available pages before exploring further. # Approve or decline an errand's purchase > Records the decision on this errand's purchase. Approving requires the signature over the payload prepared for the errand — fetch it with `?expand=mandate`, sign it with the wallet on the account, and send the signature here. What the purchase is bounded by is read from that signed payload, so an approval always means exactly what was signed. Declining is final and needs no signature. ## OpenAPI ````yaml /api-reference/openapi.json put /v0/user/ipa/{ipa_id}/decision openapi: 3.1.0 info: title: Sumvin API version: 0.35.2 servers: - url: https://api.sumvin.com description: Production security: [] tags: - name: User description: > User identity and account management for the Sumvin platform. ## Capabilities - **Account Creation** - Register new users with automatic primary wallet setup - **Profile Management** - Retrieve and update user profile information - **Phone Verification** - Two-step phone verification with SMS codes - **Resource Expansion** - Fetch related resources (wallets, status_history) in a single request ## Authentication All endpoints require a valid JWT passed in the `x-juno-jwt` header: ``` x-juno-jwt: ``` Two JWT issuers are supported by the platform's auth layer: | Issuer | Status | |--------|--------| | **Dynamic Labs** | Currently active. JWTs are validated against the configured Dynamic Labs environment. | | **Privy** | Supported by the platform's auth layer; provisioning the issuer for a given environment is a deployment-config step. Contact the team for sandbox or production credentials. | Both issuer types are accepted simultaneously when configured. Identify which provider issued a given JWT via the `auth_provider` field on the user response (`dynamic` or `privy`). ## User Lifecycle ``` ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ Register │────►│ Verify KYC │────►│ Active │ │ (pending) │ │(in_progress)│ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ ┌─────┴─────┐ ▼ ▼ ┌───────────┐ ┌───────────┐ │ Retry │ │ Rejected │ │(needs fix)│ │ (terminal)│ └─────┬─────┘ └───────────┘ │ └──► Resubmit → Review → Active ``` ## Key Concepts | Concept | Description | |---------|-------------| | `id` | Public user identifier (format: `usr_xxx`) for API references | | `auth_provider_id` | User's ID from the authentication provider (Dynamic Labs or Privy) | | `primary_eoa_address` | User's main externally-owned wallet address | | `safe_creation_status` | Async Safe wallet deployment: `processing`, `completed`, `failed` | ## Expand Parameters Use `?expand=` to include related resources: | Parameter | Description | |-----------|-------------| | `wallets` | Include all user wallets | | `status_history` | Include full audit trail of account status changes | ## Related Resources - [KYC](#tag/KYC) - Identity verification - [Wallets](#tag/Wallets) - Wallet management - name: KYC description: > Know Your Customer (KYC) identity verification via Sumsub integration. ## Capabilities - **SDK Token Generation** - Create short-lived tokens for Sumsub Web SDK - **Status Tracking** - Monitor verification progress and results - **Document Verification** - Track submitted documents and their status - **GDPR Compliance** - Access verification details with privacy-safe filtering ## Verification Flow ``` ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ Generate SDK │────►│ User does │────►│ Webhook │ │ Token │ │ verification │ │ received │ └──────────────┘ │ in Sumsub │ └──────────────┘ └──────────────┘ │ ▼ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ approved │◄────│ Review │◄────│ Processing │ │ │ │ (if needed) │ │ │ └──────────────┘ └──────┬───────┘ └──────────────┘ │ │ │ ┌─────┴─────┐ │ ▼ ▼ │ ┌───────────┐ ┌───────────┐ │ │ retry │ │ rejected │ │ │ (fixable) │ │ (terminal)│ │ └─────┬─────┘ └───────────┘ │ │ │ └──► Resubmit → Review ▼ ┌──────────────┐ │ User active │ │ Full access │ └──────────────┘ ``` ## Verification Statuses | Status | Description | |--------|-------------| | `pending` | KYC not started | | `in_progress` | Documents submitted, awaiting review | | `retry` | Additional documents or corrections needed - user CAN resubmit | | `approved` | Identity verified successfully | | `rejected` | Verification failed permanently - user CANNOT retry | ## SDK Integration 1. Call `POST /v0/kyc/access-token` to get a token 2. Initialize Sumsub Web SDK with the token 3. User completes verification in SDK 4. Poll `GET /v0/kyc/status` or listen for webhooks ## Related Resources - [User](#tag/User) - User profile management - [Webhooks](#tag/Webhooks) - KYC status change notifications - name: Wallets description: > Multi-chain wallet management supporting EOA and Safe multisig wallets. ## Capabilities - **Multi-Chain Support** - Manage wallets across Ethereum, Base, Polygon, and more - **Wallet Types** - EOA (externally owned) and Safe smart wallets - **Primary Designation** - Set primary wallet per type for default transactions - **Soft Delete** - Remove wallets while preserving transaction history ## Wallet Types | Type | Description | |------|-------------| | **EOA** | Standard Ethereum wallet controlled by private key | | **Safe** | Gnosis Safe multisig with agent key as signer | ## Creation Flow ``` ┌─────────────────┐ │ User registers │ └────────┬────────┘ │ ▼ ┌─────────────────┐ ┌─────────────────┐ │ Primary EOA set │────►│ Safe deployment │ │ immediately │ │ triggered │ └─────────────────┘ └────────┬────────┘ │ ┌────────┴────────┐ ▼ ▼ ┌──────────────┐ ┌──────────────┐ │ completed │ │ failed │ │ Safe address │ │ Retry via │ │ stored │ │ PATCH wallet│ └──────────────┘ └──────────────┘ ``` ## Primary Wallet Rules - One primary EOA and one primary Safe per user - Primary EOA and Safe must be on the same chain (`primary_chain_id`) - Changing primary wallet may trigger new Safe deployment (returns 202) ## Key Concepts | Concept | Description | |---------|-------------| | `chain_id` | EIP-155 chain identifier (e.g., 1=Ethereum, 8453=Base) | | `is_primary` | Whether this is the default wallet for its type | | `safe_creation_event_id` | Event ID for tracking async Safe deployment | | `nickname` | User-defined friendly name for the wallet | ## Filtering ``` GET /v0/wallets?chain_id=8453&is_eoa=true ``` | Parameter | Description | |-----------|-------------| | `chain_id` | Filter by blockchain | | `is_eoa` | Filter by wallet type (true=EOA, false=Safe) | ## Related Resources - [Wallet Assets](#tag/Wallet-Assets) - Asset balances per wallet - [Assets](#tag/Assets) - Supported currencies and tokens - [Transactions](#tag/Transactions) - Wallet transaction history - name: Wallet Assets description: | Asset balances and holdings within user wallets. ## Capabilities - **Balance Tracking** - Real-time asset balances per wallet - **Multi-Asset Support** - Native tokens, ERC-20s, and fiat equivalents - **Chain-Specific Data** - Balances scoped to specific blockchains ## Response Structure ```json { "wallet_id": 123, "assets": [ { "asset": { "symbol": "ETH", "name": "Ethereum", ... }, "balance": "1.5", "value_usd": "2734.50" } ], "_links": { ... } } ``` ## Key Concepts | Concept | Description | |---------|-------------| | `balance` | Raw balance in asset's base units (string for precision) | | `value_usd` | USD equivalent at current market price | | `decimals` | Asset's decimal precision for display formatting | ## Related Resources - [Wallets](#tag/Wallets) - Wallet management - [Assets](#tag/Assets) - Asset metadata and pricing - name: Assets description: > Supported currencies, tokens, and their market data. ## Capabilities - **Asset Registry** - All supported crypto and fiat currencies - **Price Feeds** - Current market prices with timestamps - **Metadata** - Symbol, name, decimals, contract addresses ## Asset Types | Type | Description | Examples | |------|-------------|----------| | `crypto` | Blockchain-native tokens | ETH, USDC, MATIC | | `fiat` | Traditional currencies | USD, EUR, GBP | ## Decimal Handling All amounts use string representation to preserve precision: | Asset | Decimals | Example | |-------|----------|---------| | ETH | 18 | `"1.500000000000000000"` | | USDC | 6 | `"100.000000"` | | USD | 2 | `"100.00"` | ## Filtering ``` GET /v0/assets?asset_type=crypto&chain_id=8453 ``` | Parameter | Description | |-----------|-------------| | `asset_type` | Filter by `crypto` or `fiat` | | `chain_id` | Filter by blockchain (crypto only) | | `symbol` | Search by ticker symbol | ## Related Resources - [Wallets](#tag/Wallets) - Wallet management - [Wallet Assets](#tag/Wallet-Assets) - Per-wallet balances - [Transactions](#tag/Transactions) - Transaction amounts use asset decimals - name: Bank Accounts description: > Linked bank account management for fiat on/off ramps. ## Capabilities - **Account Linking** - Connect external bank accounts via Open Banking - **Balance Access** - View linked account balances (where permitted) - **Transfer Support** - Enable bank-to-wallet and wallet-to-bank transfers ## Linking Flow ``` ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ Initiate link │────►│ Open Banking │────►│ Account(s) │ │ │ │ OAuth consent │ │ linked │ └─────────────────┘ └─────────────────┘ └─────────────────┘ ``` ## Key Concepts | Concept | Description | |---------|-------------| | `institution_id` | Bank identifier from Open Banking provider | | `account_type` | Checking, savings, etc. | | `currency` | Account's native currency | ## Related Resources - [Open Banking](#tag/Open-Banking) - Institution connections - [Accounts](#tag/Accounts) - Unified account view - [Transactions](#tag/Transactions) - Bank transaction history - name: Accounts description: | Unified financial account aggregation across all sources. ## Capabilities - **Account Aggregation** - View all financial accounts in one place - **Balance Tracking** - Current balances across account types - **Source Attribution** - Distinguish crypto, bank, and card accounts ## Account Sources | Source | Description | |--------|-------------| | `crypto_wallet` | Blockchain wallets (EOA, Safe) | | `bank_account` | Linked bank accounts | | `card` | Sumvin virtual cards | ## Related Resources - [Wallets](#tag/Wallets) - Crypto wallet details - [Bank Accounts](#tag/Bank-Accounts) - Bank account details - [Cards](#tag/Cards) - Card account details - name: Open Banking description: > Open Banking institution connections and OAuth flows. ## Capabilities - **Institution Discovery** - Search supported banks and financial institutions - **OAuth Integration** - Secure account linking via bank's consent flow - **Connection Management** - View and revoke institution connections ## Connection Flow ``` ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ Get link URL │────►│ User consent │────►│ Callback │ │ │ │ at bank site │ │ with code │ └─────────────────┘ └─────────────────┘ └────────┬────────┘ │ ▼ ┌─────────────────┐ │ Accounts synced │ └─────────────────┘ ``` ## Related Resources - [Bank Accounts](#tag/Bank-Accounts) - Linked account management - [Accounts](#tag/Accounts) - Unified account view - name: Cards description: > Virtual card issuance and lifecycle management. ## Capabilities - **Card Issuance** - Create virtual Visa/Mastercard cards - **Lifecycle Management** - Activate, freeze, unfreeze, and close cards - **Spending Controls** - Set transaction limits and merchant restrictions - **Card Details** - Retrieve PAN, CVV, expiry for payments ## Card States ``` ┌──────────┐ ┌──────────┐ ┌───────────┐ │ pending │────►│ active │────►│ suspended │ │ │ │ │◄────│ │ └──────────┘ └────┬─────┘ └───────────┘ │ ▼ ┌──────────┐ │ closed │ (terminal) └──────────┘ ``` ## Card Types | Type | Description | |------|-------------| | `virtual` | Digital-only card for online payments | | `physical` | Physical card (future support) | ## Spending Controls | Control | Description | |---------|-------------| | `daily_limit` | Maximum spend per day | | `monthly_limit` | Maximum spend per month | | `single_transaction_limit` | Maximum per transaction | | `allowed_mcc` | Allowed merchant category codes | | `blocked_mcc` | Blocked merchant category codes | ## Sensitive Data Card details (PAN, CVV) are returned only via dedicated secure endpoints with additional authentication. ## Related Resources - [Card Funding](#tag/Card-Funding) - Load funds to cards - [Transactions](#tag/Transactions) - Card transaction history - [Wallets](#tag/Wallets) - Funding source wallets - name: Card Funding description: | Fund virtual cards from crypto wallets or bank accounts. ## Capabilities - **Crypto Funding** - Load cards directly from crypto wallets - **Bank Funding** - Load cards from linked bank accounts - **Instant Loading** - Real-time balance updates ## Funding Flow ``` ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ Select source │────►│ Confirm USD │────►│ Card balance │ │ wallet/bank │ │ amount │ │ updated │ └─────────────────┘ └─────────────────┘ └─────────────────┘ ``` ## Funding Sources | Source | Description | |--------|-------------| | `crypto_wallet` | Convert crypto to USD and load | | `bank_account` | ACH transfer from linked bank | ## Related Resources - [Cards](#tag/Cards) - Card management - [Wallets](#tag/Wallets) - Crypto funding sources - [Bank Accounts](#tag/Bank-Accounts) - Bank funding sources - name: Transactions description: > Unified transaction history across all financial sources. ## Capabilities - **Multi-Source History** - Crypto, card, and bank transactions in one feed - **Rich Filtering** - Filter by type, status, date, amount, category - **Metadata Aggregation** - Cashflow summaries and category breakdowns - **Pagination** - Efficient access to large transaction histories ## Transaction Types | Type | Description | |------|-------------| | `deposit` | Funds received | | `withdrawal` | Funds sent out | | `transfer` | Internal transfer between accounts | | `swap` | Crypto-to-crypto exchange | | `card_purchase` | Card payment at merchant | | `card_refund` | Merchant refund to card | | `on_ramp` | Fiat to crypto conversion | | `off_ramp` | Crypto to fiat conversion | | `bank_transfer` | Bank account transfer | | `direct_debit` | Recurring bank debit | | `standing_order` | Scheduled bank payment | | `bank_payment` | Outgoing bank payment | | `bank_refund` | Bank payment reversal | | `interest` | Interest earned | | `fee` | Service fee | ## Transaction Lifecycle ``` ┌──────────┐ ┌──────────┐ ┌──────────┐ │ pending │────►│processing│────►│completed │ └──────────┘ └────┬─────┘ └──────────┘ │ ▼ ┌──────────┐ │ failed │ └──────────┘ ``` ## Filtering & Pagination ``` GET /v0/transactions?type=card_purchase&status=completed&limit=50&offset=0 ``` | Parameter | Description | |-----------|-------------| | `type` | Transaction type filter | | `status` | Status filter | | `direction` | `in` or `out` | | `wallet_id` | Filter by wallet | | `card_id` | Filter by card | | `period_start` | Start date (epoch ms) | | `period_end` | End date (epoch ms) | | `amount_min` | Minimum amount | | `amount_max` | Maximum amount | | `category` | Spending category | ## Metadata Aggregation Add `?meta=true` to include: ```json { "meta": { "transaction_count": 150, "date_range": { "earliest": "...", "latest": "..." }, "cashflow": { "gross_in": "5000.00", "gross_out": "3200.00", "net": "1800.00" }, "categories": [ { "category": "restaurants", "total_amount": "450.00", "percentage_of_total": 14.1 } ] } } ``` ## Related Resources - [Wallets](#tag/Wallets) - Crypto transaction sources - [Cards](#tag/Cards) - Card transaction sources - [Budgets](#tag/Budgets) - Category-based spending limits - [Assets](#tag/Assets) - Transaction asset details - name: Budgets description: > Category-based spending budgets and tracking. ## Capabilities - **Category Budgets** - Set spending limits by category - **Period Tracking** - Weekly, monthly, or custom periods - **Progress Monitoring** - Track spending against budget limits - **Overspend Alerts** - Notifications when approaching or exceeding limits ## Budget Structure ```json { "id": 123, "category": "restaurants", "amount": "500.00", "currency": "USD", "period": "monthly", "spent": "342.50", "remaining": "157.50", "percentage_used": 68.5 } ``` ## Periods | Period | Description | |--------|-------------| | `weekly` | Resets every Monday | | `monthly` | Resets on the 1st | | `custom` | User-defined start/end dates | ## Categories Standard spending categories: | Category | Description | |----------|-------------| | `restaurants` | Dining and food delivery | | `groceries` | Supermarkets and food stores | | `transportation` | Rideshare, gas, public transit | | `entertainment` | Movies, games, streaming | | `shopping` | Retail and online shopping | | `utilities` | Bills and subscriptions | | `travel` | Hotels, flights, vacation | | `health` | Medical, pharmacy, fitness | | `other` | Uncategorized spending | ## Related Resources - [Transactions](#tag/Transactions) - Transaction categorization - [Insights](#tag/Insights) - Spending analysis and recommendations - name: Insights description: | AI-powered financial insights and spending analysis. ## Capabilities - **Spending Analysis** - Identify patterns and trends in spending - **Anomaly Detection** - Flag unusual transactions - **Recommendations** - Actionable suggestions for saving money - **Periodic Reports** - Weekly and monthly financial summaries ## Insight Types | Type | Description | |------|-------------| | `spending_spike` | Unusual increase in category spending | | `recurring_charge` | Detected subscription or recurring payment | | `saving_opportunity` | Potential way to reduce spending | | `budget_warning` | Approaching or exceeded budget | | `goal_progress` | Progress toward financial goals | ## Related Resources - [Transactions](#tag/Transactions) - Transaction data for analysis - [Budgets](#tag/Budgets) - Budget status insights - [Strategies](#tag/Strategies) - Automated responses to insights - name: Strategies description: > Available automation templates for financial management. ## Capabilities - **Strategy Catalog** - Browse available automation templates - **Parameter Definitions** - Understand required configuration - **Category Browsing** - Find strategies by use case ## Strategy Categories | Category | Description | Examples | |----------|-------------|----------| | `savings` | Automatic saving rules | Round-up, percentage save | | `investing` | Automated investing | DCA, rebalancing | | `spending` | Spending controls | Category limits, merchant blocks | | `alerts` | Notification triggers | Large transaction, low balance | ## Related Resources - [User Strategies](#tag/User-Strategies) - Configure strategies for your account - [Agent Tasks](#tag/Agent-Tasks) - View execution history - name: User Strategies description: | User-configured automation strategies. ## Capabilities - **Strategy Configuration** - Set up strategies with custom parameters - **Enable/Disable** - Toggle strategies without deleting configuration - **Parameter Updates** - Modify strategy settings ## Configuration Flow ``` ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ Browse catalog │────►│ Configure │────►│ Enable & │ │ (Strategies) │ │ parameters │ │ start running │ └─────────────────┘ └─────────────────┘ └─────────────────┘ ``` ## Strategy States | State | Description | |-------|-------------| | `enabled` | Actively running | | `disabled` | Configured but paused | | `error` | Failed, needs attention | ## Related Resources - [Strategies](#tag/Strategies) - Available templates - [Agent Tasks](#tag/Agent-Tasks) - Execution history - name: Agent Tasks description: | Agent task execution history and results. ## Capabilities - **Execution History** - View all agent tasks - **Task Details** - See inputs, outputs, and any errors - **Manual Triggers** - Force immediate strategy execution - **Filtering** - Find tasks by strategy, status, or date ## Task Lifecycle ``` ┌────────┐ ┌────────┐ ┌─────────┐ ┌──────────┐ │ queued │────►│ next │────►│ running │────►│ completed│ └────────┘ └────────┘ └────┬────┘ └──────────┘ │ ┌───────────┼───────────┐ ▼ ▼ ┌──────────┐ ┌───────────┐ │ failed │ │ cancelled │ └──────────┘ └───────────┘ ``` ## Task Statuses | Status | Description | |--------|-------------| | `queued` | Created, waiting to be scheduled | | `next` | Promoted to next slot, about to run | | `running` | Currently executing | | `completed` | Finished successfully | | `failed` | Encountered an error | | `cancelled` | Cancelled before completion | ## Related Resources - [User Strategies](#tag/User-Strategies) - Strategy configuration - [Strategies](#tag/Strategies) - Strategy definitions - name: Chat description: | Conversational AI interface for financial management. ## Capabilities - **Natural Language** - Interact with your finances conversationally - **Session Management** - Maintain conversation context - **Tool Integration** - AI can execute actions on your behalf - **History Access** - Review past conversations ## Session Flow ``` ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ Create session │────►│ Send messages │────►│ AI responds │ │ │ │ │◄────│ (may use tools)│ └─────────────────┘ └─────────────────┘ └─────────────────┘ ``` ## Message Types | Type | Description | |------|-------------| | `user` | Message from the user | | `assistant` | Response from AI | | `tool_call` | AI requesting to execute an action | | `tool_result` | Result of tool execution | ## Related Resources - [Agent](#tag/Agent) - Agent authentication - [Widgets](#tag/Widgets) - Embeddable chat components - name: Widgets description: | Embeddable UI components for external integration. ## Capabilities - **Widget Configuration** - Customize appearance and behavior - **Embed Codes** - Get HTML/JS snippets for embedding - **Data Binding** - Connect widgets to user data ## Widget Types | Type | Description | |------|-------------| | `balance` | Display account balances | | `transactions` | Transaction list or feed | | `chat` | Conversational interface | | `budget` | Budget progress visualization | ## Related Resources - [Chat](#tag/Chat) - Chat widget backend - [Transactions](#tag/Transactions) - Transaction widget data - name: Connectors description: > Available external service integrations. ## Capabilities - **Connector Catalog** - Browse available integrations - **Capability Discovery** - Understand what each connector provides - **Authentication Requirements** - Know what's needed to connect ## Connector Types | Type | Description | |------|-------------| | `exchange` | Crypto exchanges (Coinbase, Binance) | | `bank` | Banking integrations | | `accounting` | Accounting software | | `tax` | Tax reporting services | ## Related Resources - [User Connectors](#tag/User-Connectors) - Connect services to your account - name: User Connectors description: | User's active external service connections. ## Capabilities - **Connection Management** - Add and remove integrations - **OAuth Flows** - Secure authorization with external services - **Sync Status** - Monitor data synchronization - **Credential Updates** - Refresh expired authorizations ## Connection Flow ``` ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ Select connector│────►│ OAuth flow │────►│ Connected & │ │ from catalog │ │ with service │ │ syncing │ └─────────────────┘ └─────────────────┘ └─────────────────┘ ``` ## Connection States | State | Description | |-------|-------------| | `connected` | Active and syncing | | `disconnected` | Removed by user | | `error` | Authorization expired or failed | ## Related Resources - [Connectors](#tag/Connectors) - Available integrations - name: User Rules description: | Custom automation rules with trigger conditions. ## Capabilities - **Rule Creation** - Define custom automation logic - **Trigger Conditions** - Set when rules should execute - **Action Configuration** - Define what happens when triggered - **Rule Management** - Enable, disable, and edit rules ## Rule Structure ``` WHEN [trigger condition] THEN [action] ``` ## Trigger Types | Trigger | Description | |---------|-------------| | `transaction_received` | New incoming transaction | | `balance_threshold` | Balance crosses amount | | `time_based` | Scheduled execution | | `price_alert` | Asset price condition | ## Action Types | Action | Description | |--------|-------------| | `transfer` | Move funds between accounts | | `notification` | Send alert to user | | `strategy_trigger` | Execute a strategy | ## Related Resources - [Strategies](#tag/Strategies) - Pre-built automation templates - [User Strategies](#tag/User-Strategies) - Active automations - name: Agent description: | Agent authentication tokens for AI-powered operations. ## Capabilities - **Token Generation** - Create scoped access tokens for agents - **Scope Control** - Limit agent capabilities - **Token Rotation** - Refresh tokens securely ## Token Scopes | Scope | Description | |-------|-------------| | `read:transactions` | View transaction history | | `read:balances` | View account balances | | `write:transfers` | Execute transfers | | `write:strategies` | Manage strategies | ## Usage Include agent token in requests: ``` x-sumvin-token: ``` ## Related Resources - [Chat](#tag/Chat) - Conversational AI interface - [Strategies](#tag/Strategies) - Agent-executable automations - name: Webhooks description: > Incoming webhook handlers for third-party provider integrations. ## Overview These endpoints receive event notifications FROM external providers (Sumsub, Meld) and process them to update user state. They are NOT for developers to subscribe to - they are internal integration endpoints. ## Supported Providers | Provider | Endpoint | Purpose | |----------|----------|---------| | **Sumsub** | `POST /v0/webhooks/kyc/sumsub/events` | KYC verification status updates | | **Meld** | `POST /v0/webhooks/meld/events` | Bank-linking and crypto on/off-ramp events | ## Sumsub Webhook Events KYC status changes are received from Sumsub and update user verification status: | Sumsub Event | Result | |--------------|--------| | `applicantReviewed` (GREEN) | User approved, status → `approved` | | `applicantReviewed` (RED) | User rejected, status → `rejected` | | `applicantPending` | Additional review needed, status → `retry` | ## Security Both endpoints validate incoming requests using provider-specific signature verification before processing. ## Future: Outgoing Webhooks Developer-facing outgoing webhooks (event subscriptions for your applications) are planned but not yet implemented. ## Related Resources - [KYC](#tag/KYC) - KYC verification flow - [Open Banking](#tag/Open-Banking) - Bank connection management - name: Health description: | System health checks and service status. ## Capabilities - **Liveness Check** - Verify API is responding - **Readiness Check** - Verify all dependencies are available - **Service Status** - Individual component health ## Endpoints | Endpoint | Purpose | |----------|---------| | `GET /health` | Quick liveness check (returns 200 if alive) | ## Response Codes | Code | Meaning | |------|---------| | `200` | Service healthy and ready | | `503` | Service degraded or dependencies unavailable | ## Usage Use for: - Load balancer health checks - Kubernetes liveness/readiness probes - Monitoring and alerting - name: AgentTool description: > Endpoints designed for AI agent consumption. ## Overview Endpoints tagged with `AgentTool` are optimized for programmatic access by AI agents. They typically: - Return structured data suitable for LLM processing - Include clear field descriptions - Support filtering for focused queries - Are read-heavy (prefer GET operations) ## Usage Pattern AI agents should: 1. Authenticate with an agent token (see [Agent](#tag/Agent)) 2. Use these endpoints to gather information 3. Present findings to users or execute follow-up actions ## Available Operations AgentTool-tagged operations span multiple resources: - **Wallets** - List and retrieve wallet details - **Transactions** - Query transaction history - **Cards** - Card information and management - **Budgets** - Budget status and tracking - **Accounts** - Account balances and details - **Agent Tasks** - Automation execution status ## Related Resources - [Agent](#tag/Agent) - Token management for agents - [Chat](#tag/Chat) - Conversational interface using these tools paths: /v0/user/ipa/{ipa_id}/decision: put: tags: - IPA summary: Approve or decline an errand's purchase description: >- Records the decision on this errand's purchase. Approving requires the signature over the payload prepared for the errand — fetch it with `?expand=mandate`, sign it with the wallet on the account, and send the signature here. What the purchase is bounded by is read from that signed payload, so an approval always means exactly what was signed. Declining is final and needs no signature. operationId: approve_ipa_v0_user_ipa__ipa_id__decision_put parameters: - name: ipa_id in: path required: true schema: type: string title: Ipa Id - name: x-juno-orgid in: header required: false schema: anyOf: - type: string - type: 'null' description: Tenant org ID for multi-tenant auth title: X-Juno-Orgid description: Tenant org ID for multi-tenant auth - name: x-sumvin-token in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Sumvin-Token - name: x-sumvin-pat in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Sumvin-Pat - name: x-juno-jwt in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Juno-Jwt - $ref: '#/components/parameters/XTimestampFormat' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ApproveIPARequest' responses: '200': description: Decision recorded content: application/json: schema: $ref: '#/components/schemas/IPADetailResponse' '400': description: The request is invalid, or the errand is not awaiting a decision content: application/json: schema: $ref: '#/components/schemas/ProblemDetail' '401': description: >- No signature was supplied, or the signature does not come from the wallet on the account content: application/json: schema: $ref: '#/components/schemas/ProblemDetail' '403': description: >- Only the account owner can decide a purchase, from the app or the command line. Anything acting on their behalf is refused. content: application/json: schema: $ref: '#/components/schemas/ProblemDetail' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ProblemDetail' '409': description: >- There is no approval awaiting a signature, or a decision on this errand has already been recorded content: application/json: schema: $ref: '#/components/schemas/ProblemDetail' '422': description: The approval was prepared for a different wallet content: application/json: schema: $ref: '#/components/schemas/ProblemDetail' '424': description: The signature could not be verified right now content: application/json: schema: $ref: '#/components/schemas/ProblemDetail' security: - PintBearer: [] - SumvinPAT: [] components: parameters: XTimestampFormat: name: X-Timestamp-Format in: header required: false description: >- Controls how timestamp fields are serialized in JSON response bodies. **Default (header omitted or any other value):** epoch milliseconds as integers. **`iso8601`:** UTC ISO 8601 strings of the form `YYYY-MM-DDTHH:MM:SSZ`. Example: with `X-Timestamp-Format: iso8601`, the field value `1704067200000` becomes `"2024-01-01T00:00:00Z"`. Affected fields (recursively, in dicts and arrays): any field whose name ends in `_at`, plus the literal field names `timestamp`, `period_start`, and `period_end`. All other fields are passed through unchanged. Only `iso8601` is recognized. Any other value (or omitting the header) yields the default epoch-ms representation; the server does not reject unknown values, so this is documented as an example rather than an enum to keep generated clients permissive. schema: type: string example: iso8601 example: iso8601 schemas: ApproveIPARequest: properties: decision: $ref: '#/components/schemas/ApprovalDecision' description: Whether to approve or decline this errand's purchase. signature: anyOf: - type: string pattern: ^0x[0-9a-fA-F]{130}$ - type: 'null' title: Signature description: >- The signature over the payload prepared for this errand, as returned by your wallet. Required to approve; omit it to decline. type: object required: - decision title: ApproveIPARequest description: >- A decision on an errand's purchase, and the signature that authorises it. Approving requires the signature over the payload prepared for this errand. What the purchase is bounded by — its ceiling, its conditions, its deadline — is read from that signed payload, never from this request: an approval must mean exactly what was signed. Declining needs no signature. IPADetailResponse: properties: _links: additionalProperties: $ref: '#/components/schemas/Link' type: object title: Links description: HAL-style hypermedia links for navigation and available actions. intent: $ref: '#/components/schemas/IPAData' type: object required: - _links - intent title: IPADetailResponse ProblemDetail: properties: type: type: string title: Type description: >- URI reference identifying the problem type. Format: https://api.sumvin.com/errors/{error_code} title: type: string title: Title description: >- Short, human-readable summary of the problem type. Does not change between occurrences. status: type: integer title: Status description: HTTP status code for this error response. detail: type: string title: Detail description: >- Human-readable explanation specific to this occurrence of the problem. instance: type: string title: Instance description: >- URI reference identifying the specific occurrence (typically the request path). error_code: $ref: '#/components/schemas/APIErrorCode' description: >- Machine-readable error code for programmatic handling. Format: {DOMAIN}-{STATUS}-{SEQUENCE} trace_id: anyOf: - type: string - type: 'null' title: Trace Id description: >- Correlation ID for tracing this request. Include when contacting support. type: object required: - type - title - status - detail - instance - error_code title: ProblemDetail description: >- RFC 7807 Problem Details response for API errors. All error responses follow this standard format, enabling consistent error handling across different clients. The `error_code` field provides a machine-readable identifier for programmatic error handling, while `detail` provides human-readable context. Error codes follow the pattern `{DOMAIN}-{HTTP_STATUS}-{SEQUENCE}`. Domain prefixes in use today: ACC (account), AGT (agent token), ALC (Alchemy webhook), AST (asset), BNK (bank), BUD (budget), CALLER (request credentials), CHA (chat attachment), CHT (chat session), CLI (command-line sign-in & personal access tokens), CON (connector), CRD (card), DMO (Visa checkout demo), DYN (Dynamic credential), FAC (facilitator), GATE (feature gate), GEN (general validation), HEALTH (health check), IDT (identity token), INS (insight), IPA (intelligent purchase authorization), KYC (KYC/verification), MLD (MELD), MRC (merchant search), OBK (open banking), ONB (onboarding), ORG (organisation), PAY (payment link), PFP (profile picture), PHONE (phone verification), PINT (payment intent token), PRV (provider), RCT (receipt), RMP (ramp), RPC (RPC usage), RUL (rule), RUN (strategy run), SAF (Safe smart contract), SGN (signer setup), SIS (Sumvin Integration Services), SIW (Sign-In With Ethereum), SRI (Sumvin Resource Identifier), STR (strategy), STS (user status), SYS (system), TAP (Trusted Agent Protocol), TOL (tool), TXN (transaction), UCO (user connector), USR (user), UST (user strategy), VIC (Visa checkout), WAL (wallet), WID (widget). See the Error Reference section for a complete list of error codes and recovery actions. example: detail: No wallet found with ID 12345 for this user. error_code: WAL-404-001 instance: /v0/wallets/12345 status: 404 title: Wallet Not Found trace_id: abc123-def456-ghi789 type: https://api.sumvin.com/errors/wal-404-001 ApprovalDecision: type: string enum: - approved - rejected - conditional title: ApprovalDecision Link: properties: href: type: string title: Href description: URL to the linked resource or action endpoint. method: type: string title: Method description: >- HTTP method to use when following this link. GET for navigation, POST/PUT/DELETE for actions. default: GET templated: type: boolean title: Templated description: >- If true, href contains URI template variables (e.g., {id}) that must be substituted. default: false description: anyOf: - type: string - type: 'null' title: Description description: Human-readable description of what this link does. type: object required: - href title: Link description: >- HAL-style hypermedia link for resource navigation and actions. Links enable clients to discover available actions and navigate related resources without hardcoding URLs. Action links include the HTTP method to use. IPAData: properties: id: type: string title: Id intent_type: $ref: '#/components/schemas/IPAType' status: $ref: '#/components/schemas/IPAStatus' autonomy_level: $ref: '#/components/schemas/AutonomyLevel' raw_intent: anyOf: - type: string - type: 'null' title: Raw Intent specification: anyOf: - type: string - type: 'null' title: Specification constraints: anyOf: - $ref: '#/components/schemas/IPAConstraint' - type: 'null' conditions: anyOf: - items: oneOf: - $ref: '#/components/schemas/PriceTargetCondition-Output' - $ref: '#/components/schemas/BudgetCapCondition-Output' - $ref: '#/components/schemas/AvailabilityCondition' - $ref: '#/components/schemas/TimeWindowCondition' - $ref: '#/components/schemas/FlightRouteCondition' - $ref: '#/components/schemas/CoverageMinimumCondition' - $ref: '#/components/schemas/JurisdictionCondition' - $ref: '#/components/schemas/ConditionGroup-Output' discriminator: propertyName: type mapping: availability: $ref: '#/components/schemas/AvailabilityCondition' budget_cap: $ref: '#/components/schemas/BudgetCapCondition-Output' coverage_minimum: $ref: '#/components/schemas/CoverageMinimumCondition' flight_route: $ref: '#/components/schemas/FlightRouteCondition' group: $ref: '#/components/schemas/ConditionGroup-Output' jurisdiction: $ref: '#/components/schemas/JurisdictionCondition' price_target: $ref: '#/components/schemas/PriceTargetCondition-Output' time_window: $ref: '#/components/schemas/TimeWindowCondition' type: array - type: 'null' title: Conditions monitor_until: anyOf: - type: integer - type: 'null' title: Monitor Until clarification_questions: anyOf: - items: type: string type: array - type: 'null' title: Clarification Questions failure_reason: anyOf: - type: string - type: 'null' title: Failure Reason pint_uris: anyOf: - items: type: string type: array - type: 'null' title: Pint Uris created_at: type: integer title: Created At updated_at: anyOf: - type: integer - type: 'null' title: Updated At completed_at: anyOf: - type: integer - type: 'null' title: Completed At capacity: anyOf: - $ref: '#/components/schemas/MandateCapacityData' - type: 'null' manifest_summary: anyOf: - $ref: '#/components/schemas/ManifestSummaryData' - type: 'null' preflight_workflow_id: anyOf: - type: string - type: 'null' title: Preflight Workflow Id originating_agent_task: anyOf: - $ref: '#/components/schemas/AgentTaskSummaryData' - type: 'null' executing_agent_task: anyOf: - $ref: '#/components/schemas/AgentTaskSummaryData' - type: 'null' candidates: anyOf: - items: $ref: '#/components/schemas/IPACandidateData' type: array - type: 'null' title: Candidates manifests: anyOf: - items: $ref: '#/components/schemas/IPAManifestData' type: array - type: 'null' title: Manifests events: anyOf: - items: $ref: '#/components/schemas/IPAEventData' type: array - type: 'null' title: Events approval_payload: anyOf: - $ref: '#/components/schemas/EIP712Payload' - type: 'null' type: object required: - id - intent_type - status - autonomy_level - created_at title: IPAData APIErrorCode: type: string enum: - USR-208-001 - USR-404-001 - USR-401-001 - USR-401-002 - USR-400-001 - USR-424-001 - USR-409-002 - USR-400-002 - USR-404-002 - USR-429-001 - PFP-400-001 - PFP-400-002 - PFP-500-001 - PFP-500-002 - PFP-404-001 - PFP-429-001 - WAL-404-001 - WAL-409-001 - WAL-403-001 - WAL-403-002 - WAL-400-001 - WAL-400-002 - WAL-403-003 - WAL-403-004 - WAL-400-003 - WAL-400-004 - WAL-400-005 - WAL-400-006 - WAL-400-007 - WAL-409-002 - KYC-400-001 - KYC-400-002 - KYC-500-001 - KYC-403-001 - KYC-403-002 - KYC-401-001 - KYC-500-002 - KYC-502-001 - KYC-404-001 - KYC-500-003 - KYC-500-004 - KYC-409-001 - KYC-502-002 - KYC-401-002 - KYC-502-003 - KYC-400-003 - KYC-409-002 - KYC-501-001 - KYC-502-004 - KYC-400-004 - KYC-409-003 - KYC-409-004 - KYC-404-002 - KYC-409-005 - KYC-409-006 - KYC-403-003 - KYC-410-001 - KYC-429-001 - KYC-503-001 - KYC-422-001 - SAF-202-001 - SAF-500-001 - SAF-502-001 - SAF-400-001 - SAF-400-002 - SAF-404-001 - SAF-424-001 - SAF-403-001 - SAF-400-003 - SAF-429-001 - SAF-404-002 - SAF-404-003 - SAF-424-002 - SAF-424-003 - SAF-424-004 - IDT-424-001 - SAF-400-004 - SAF-400-005 - SAF-502-002 - SAF-502-003 - SAF-502-004 - SAF-502-005 - SAF-409-001 - SAF-503-005 - SAF-400-006 - SAF-400-007 - SAF-400-008 - SAF-502-006 - SAF-400-009 - SAF-400-010 - SAF-400-011 - SAF-400-012 - SAF-400-013 - SAF-400-014 - SAF-400-015 - SAF-409-002 - SAF-502-007 - SAF-400-016 - SAF-503-001 - SAF-503-002 - SAF-503-003 - SAF-503-004 - SGN-404-001 - SGN-404-002 - SGN-422-001 - SGN-500-001 - SGN-500-002 - SGN-502-001 - SGN-502-002 - SGN-502-003 - SGN-502-004 - HEALTH-401-001 - STS-400-001 - STS-404-001 - STS-403-001 - STS-403-002 - ONB-409-001 - ONB-202-001 - PHONE-409-001 - PHONE-400-001 - PHONE-422-002 - PHONE-400-003 - PHONE-429-001 - PHONE-429-002 - PHONE-409-002 - PHONE-502-001 - PHONE-403-001 - STR-404-001 - STR-409-001 - STR-400-001 - CON-404-001 - CON-409-001 - CON-401-001 - CON-400-001 - UST-404-001 - UST-403-001 - UST-400-001 - UST-409-001 - UST-503-001 - UCO-404-001 - UCO-403-001 - TOL-404-001 - RUL-404-001 - RUL-403-001 - RUL-400-001 - RUN-404-001 - RUN-403-001 - RUN-409-001 - RUN-400-001 - RUN-400-002 - RUN-404-002 - RUN-409-002 - RUN-409-003 - RUN-208-001 - RUN-400-003 - RUN-408-001 - ACC-404-001 - ACC-409-001 - ACC-403-001 - ACC-400-001 - ACC-400-002 - ACC-502-001 - ACC-403-002 - OBK-401-001 - OBK-400-001 - OBK-502-001 - TXN-404-001 - TXN-403-001 - TXN-500-001 - TXN-400-001 - TXN-400-002 - TXN-409-001 - TXN-409-002 - TXN-409-003 - TXN-422-001 - RCT-400-001 - RCT-400-002 - RCT-500-001 - RCT-404-001 - RCT-500-002 - RCT-500-003 - RCT-429-001 - INS-404-001 - INS-403-001 - INS-409-001 - INS-400-001 - INS-500-002 - INS-500-003 - INS-503-001 - CRD-404-001 - CRD-403-001 - CRD-404-002 - CRD-400-001 - CRD-403-002 - CRD-401-001 - CRD-404-003 - CRD-409-001 - CRD-502-001 - BUD-404-001 - BUD-403-001 - BUD-409-001 - BUD-400-001 - BUD-400-002 - BUD-400-003 - BUD-400-004 - BUD-400-005 - BUD-403-002 - BUD-500-001 - BUD-429-001 - CHT-404-001 - CHT-403-001 - CHT-404-002 - CHT-409-001 - CHT-400-001 - CHA-415-001 - CHA-413-001 - CHA-500-001 - CHA-429-001 - AGT-401-001 - AGT-401-002 - AGT-401-003 - AGT-401-004 - AGT-401-005 - AGT-403-001 - AGT-403-002 - AGT-404-001 - AGT-404-002 - AGT-429-001 - AST-404-001 - AST-502-001 - AST-400-001 - BNK-500-001 - BNK-400-001 - BNK-404-001 - BNK-403-001 - BNK-409-001 - BNK-400-002 - BNK-202-001 - BNK-400-003 - BNK-400-004 - BNK-502-001 - BNK-410-001 - BNK-403-002 - BNK-400-005 - BNK-400-006 - BNK-404-002 - BNK-403-003 - BNK-422-001 - WID-404-001 - WID-403-001 - WID-400-001 - WID-400-002 - GATE-403-001 - GATE-429-001 - GATE-503-001 - SIS-401-001 - SIS-401-002 - SIS-404-001 - SIS-403-001 - SIS-403-002 - SIS-403-003 - SIS-404-002 - SIS-403-004 - SIS-403-005 - SIS-403-006 - SIS-409-001 - SIS-409-002 - SIS-404-003 - SIS-502-001 - SIS-502-002 - SIS-502-003 - SIS-401-003 - SIS-409-003 - SIS-502-004 - SIS-502-005 - SIS-409-004 - SIS-409-005 - SIS-400-001 - ORG-401-001 - ORG-503-001 - SIS-404-004 - SIS-409-006 - SIS-422-002 - SIS-404-005 - SIS-422-003 - SIS-404-006 - SIS-404-007 - SIS-422-004 - SIS-409-008 - SIS-404-008 - SIS-409-007 - SIS-422-005 - SIS-422-006 - SIS-422-007 - SIS-502-006 - PINT-400-001 - PINT-400-002 - PINT-400-003 - PINT-400-004 - PINT-400-005 - PINT-400-006 - PINT-400-007 - PINT-401-001 - PINT-401-002 - PINT-401-005 - PINT-403-001 - PINT-403-002 - PINT-404-001 - PINT-409-001 - PINT-409-002 - PINT-409-003 - PINT-409-004 - PINT-409-005 - PINT-410-001 - PINT-410-002 - PINT-424-001 - PINT-424-002 - PINT-424-003 - PINT-424-004 - PINT-424-005 - PINT-424-006 - PINT-424-007 - PINT-429-001 - PINT-401-003 - PINT-401-004 - PINT-401-006 - PINT-403-003 - PINT-403-004 - PINT-403-005 - PINT-403-006 - PINT-403-007 - PINT-403-008 - PINT-409-006 - PINT-422-001 - PINT-422-002 - PINT-422-003 - PINT-422-004 - PINT-422-005 - PINT-422-006 - PINT-500-001 - PAY-404-001 - PAY-403-001 - PAY-409-001 - PAY-409-002 - PAY-409-003 - PAY-410-001 - PAY-422-001 - PAY-422-002 - PAY-400-003 - PAY-400-004 - PAY-400-005 - PAY-400-006 - PAY-422-003 - PAY-501-001 - PAY-502-001 - PAY-504-001 - FAC-400-001 - FAC-400-002 - FAC-400-003 - FAC-400-004 - FAC-400-005 - FAC-409-001 - FAC-422-001 - FAC-422-002 - FAC-422-003 - FAC-502-001 - FAC-502-002 - FAC-503-001 - SRI-400-001 - SRI-400-002 - SRI-404-001 - SRI-400-003 - SIW-401-001 - SIW-401-002 - SIW-401-003 - SIW-401-004 - SIW-401-005 - SIW-401-006 - SIW-400-001 - SIW-400-002 - SIW-502-001 - SIW-429-001 - SIW-429-002 - SIW-404-001 - SIW-404-002 - SIW-401-007 - SIW-401-008 - SIW-401-009 - SIW-401-010 - IPA-404-001 - IPA-400-001 - IPA-400-002 - IPA-409-001 - IPA-403-001 - IPA-401-001 - IPA-401-002 - IPA-401-003 - IPA-401-004 - IPA-409-002 - IPA-409-003 - IPA-422-001 - IPA-424-001 - IPA-409-004 - IPA-409-005 - IPA-422-002 - IPA-424-002 - IPA-409-006 - ALC-401-001 - ALC-400-001 - MLD-401-001 - MLD-502-001 - RMP-400-001 - RMP-400-002 - RMP-400-003 - RMP-400-004 - RMP-403-001 - RMP-403-002 - RMP-404-001 - RMP-502-001 - ONB-400-001 - ONB-400-002 - ONB-400-003 - ONB-400-004 - ONB-409-003 - ONB-409-002 - PRV-404-001 - MRC-404-001 - MRC-400-001 - MRC-401-001 - MRC-403-001 - MRC-503-001 - RPC-400-001 - RPC-404-002 - RPC-402-001 - RPC-404-001 - RPC-400-002 - RPC-502-001 - RPC-409-001 - RPC-409-002 - RPC-409-003 - RPC-401-001 - RPC-403-001 - CLI-400-001 - CLI-401-001 - CLI-401-002 - CLI-401-003 - CLI-401-004 - CLI-403-001 - CLI-404-001 - CLI-409-001 - CLI-410-001 - CLI-503-001 - CALLER-400-001 - CALLER-403-001 - CALLER-503-001 - DMO-403-001 - VIC-404-001 - VIC-409-001 - VIC-409-002 - VIC-409-003 - VIC-502-001 - VIC-502-002 - VIC-502-003 - VIC-502-004 - VIC-502-005 - VIC-503-001 - TAP-503-001 - TAP-502-001 - GEN-400-001 - SYS-500-001 title: APIErrorCode IPAType: type: string enum: - product - service - composite title: IPAType description: >- What kind of purchase an errand is for. `product` is physical or digital goods. `service` covers bookings such as flights, hotels or reservations. `composite` is a purchase made of several parts bought together, such as a trip. IPAStatus: type: string enum: - qualifying - searching - validating - pending_approval - pending_clarification - approved - monitoring - executing - completed - failed - expired - cancelled title: IPAStatus description: >- How far an errand has got. While an agent is working out what to buy it reads as `qualifying`, `searching` or `validating`. It then waits for the user: `pending_clarification` needs a question answered, `pending_approval` needs the purchase approved. Once `approved` it may sit in `monitoring` until the conditions it was given are met, and reads as `executing` while the purchase is being made. `completed`, `failed`, `expired` and `cancelled` are final. An errand in one of those four states will not change again, and can no longer be clarified or cancelled. What may be done to an errand follows from where it has got to. Cancelling works in any of the eight states that are not final. Answering questions works only while the errand is actually waiting on some — `qualifying` or `pending_clarification` — and is refused everywhere else, so its state is worth reading before trying. AutonomyLevel: type: string enum: - supervised - approve_before_purchase - auto_within_conditions - autonomous title: AutonomyLevel description: >- How much an errand may do without asking the user again. `approve_before_purchase` is the default: an agent may search and prepare, but the user approves before any money is spent. `supervised` also stops for the user at each meaningful step along the way. `auto_within_conditions` and `autonomous` both let a purchase complete with no further approval — the first once the errand's conditions are met, the second whenever its constraints allow. Neither should be chosen unless the user has clearly asked for spending to happen unattended. IPAConstraint: properties: max_price: anyOf: - type: number - type: 'null' title: Max Price description: Maximum acceptable per-item price for proposed options. max_total: anyOf: - type: number - type: 'null' title: Max Total description: Maximum acceptable total price across all items in the purchase. currency: anyOf: - type: string - type: 'null' title: Currency description: >- Currency for any price-based constraints (ISO 4217, e.g. 'GBP', 'USD'). deadline: anyOf: - type: integer - type: 'null' title: Deadline description: Latest acceptable delivery or fulfilment date (epoch milliseconds). preferred_sellers: anyOf: - items: type: string type: array - type: 'null' title: Preferred Sellers description: Preferred sellers or marketplaces to include in search results. excluded_sellers: anyOf: - items: type: string type: array - type: 'null' title: Excluded Sellers description: Sellers or marketplaces that must not be proposed. extra: anyOf: - additionalProperties: true type: object - type: 'null' title: Extra description: >- Additional domain-specific constraints not covered by the standard fields (e.g. brands, item_conditions, quantity). type: object title: IPAConstraint description: >- Selection filters and guardrails that define what purchase options are acceptable. These affect what the system may propose, not when it may act. For auto-execution triggers, use `conditions` on the parent request. PriceTargetCondition-Output: properties: type: type: string const: price_target title: Type operator: $ref: '#/components/schemas/ComparisonOp' description: Comparison operator applied to lowest offer price vs target_price. target_price: type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ title: Target Price description: Threshold price value used by the trigger. currency: type: string title: Currency description: Currency for the price target (ISO 4217). default: USD type: object required: - type - operator - target_price title: PriceTargetCondition description: >- Auto-execute when the lowest offer price satisfies a comparison against a target. BudgetCapCondition-Output: properties: type: type: string const: budget_cap title: Type max_total: type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ title: Max Total description: Maximum basket total that permits auto-execution. currency: type: string title: Currency description: Currency for the budget cap (ISO 4217). default: USD type: object required: - type - max_total title: BudgetCapCondition description: Auto-execute when the basket total is within the budget cap. AvailabilityCondition: properties: type: type: string const: availability title: Type required_statuses: items: type: string type: array title: Required Statuses description: >- Offer availability statuses that permit auto-execution (e.g. 'in_stock', 'pre_order'). type: object required: - type title: AvailabilityCondition description: >- Auto-execute when at least one offer matches a required availability status. TimeWindowCondition: properties: type: type: string const: time_window title: Type not_before: anyOf: - type: integer - type: 'null' title: Not Before description: Earliest time auto-execution is permitted (epoch milliseconds). not_after: anyOf: - type: integer - type: 'null' title: Not After description: Latest time auto-execution is permitted (epoch milliseconds). type: object required: - type title: TimeWindowCondition description: Auto-execute only within a specified time window. FlightRouteCondition: properties: type: type: string const: flight_route title: Type origin: type: string title: Origin description: Departure airport code (IATA). destination: type: string title: Destination description: Arrival airport code (IATA). max_stops: anyOf: - type: integer - type: 'null' title: Max Stops description: Maximum number of stops (0 = direct only). type: object required: - type - origin - destination title: FlightRouteCondition description: Auto-execute when a flight matching the route requirements is found. CoverageMinimumCondition: properties: type: type: string const: coverage_minimum title: Type min_coverage_pct: type: number title: Min Coverage Pct description: Minimum coverage percentage required (0-100). type: object required: - type - min_coverage_pct title: CoverageMinimumCondition description: Auto-execute when coverage percentage meets the minimum threshold. JurisdictionCondition: properties: type: type: string const: jurisdiction title: Type allowed_jurisdictions: items: type: string type: array title: Allowed Jurisdictions description: ISO 3166-1 alpha-2 country codes where execution is permitted. type: object required: - type - allowed_jurisdictions title: JurisdictionCondition description: >- Auto-execute only when the seller or service is in an allowed jurisdiction. ConditionGroup-Output: properties: type: type: string const: group title: Type operator: type: string enum: - AND - OR title: Operator description: 'Logical operator: AND (all must be met) or OR (any must be met).' conditions: items: oneOf: - $ref: '#/components/schemas/PriceTargetCondition-Output' - $ref: '#/components/schemas/BudgetCapCondition-Output' - $ref: '#/components/schemas/AvailabilityCondition' - $ref: '#/components/schemas/TimeWindowCondition' - $ref: '#/components/schemas/FlightRouteCondition' - $ref: '#/components/schemas/CoverageMinimumCondition' - $ref: '#/components/schemas/JurisdictionCondition' - $ref: '#/components/schemas/ConditionGroup-Output' discriminator: propertyName: type mapping: availability: $ref: '#/components/schemas/AvailabilityCondition' budget_cap: $ref: '#/components/schemas/BudgetCapCondition-Output' coverage_minimum: $ref: '#/components/schemas/CoverageMinimumCondition' flight_route: $ref: '#/components/schemas/FlightRouteCondition' group: $ref: '#/components/schemas/ConditionGroup-Output' jurisdiction: $ref: '#/components/schemas/JurisdictionCondition' price_target: $ref: '#/components/schemas/PriceTargetCondition-Output' time_window: $ref: '#/components/schemas/TimeWindowCondition' type: array minItems: 1 title: Conditions description: Nested conditions evaluated according to the operator. type: object required: - type - operator - conditions title: ConditionGroup description: Logical grouping of conditions with AND/OR semantics. MandateCapacityData: properties: mandate_pint_uri: anyOf: - type: string - type: 'null' title: Mandate Pint Uri description: Identifier of the mandate authorizing this errand, if one is linked. limit_status: $ref: '#/components/schemas/MandateLimitStatus' description: >- Whether the mandate carries a spend limit, and whether the amount still available under it could be worked out. max_amount: anyOf: - type: string - type: 'null' title: Max Amount description: >- Maximum the mandate permits to be spent — the same limit a purchase is checked against when it is made. Null when the mandate authorizes no amount. consumed: type: string title: Consumed description: Total already settled against the mandate. reserved: type: string title: Reserved description: >- Amount held by spending in flight against the mandate that has not yet settled. remaining: anyOf: - type: string - type: 'null' title: Remaining description: >- Amount still available to spend under the mandate's limit. Null when that amount is not known. asset: anyOf: - type: string - type: 'null' title: Asset description: Asset the amounts are denominated in. enforcement_mode: type: string title: Enforcement Mode description: >- Whether exceeding the mandate blocks a purchase (strict) or only records a warning (advisory). type: object required: - limit_status - consumed - reserved - enforcement_mode title: MandateCapacityData description: Remaining spend capacity of the mandate that authorizes an errand. ManifestSummaryData: properties: id: type: string title: Id description: Identifier of the manifest. status: type: string title: Status description: Current status of the manifest. total_amount: anyOf: - type: string - type: 'null' title: Total Amount description: Total cost of the manifest, if it has been priced. total_asset: anyOf: - type: string - type: 'null' title: Total Asset description: Asset the total is denominated in. item_count: type: integer title: Item Count description: Number of line items in the manifest. approved_at: anyOf: - type: integer - type: 'null' title: Approved At description: When the manifest was approved, if it has been. purchased_at: anyOf: - type: integer - type: 'null' title: Purchased At description: When the manifest was purchased, if it has been. type: object required: - id - status - item_count title: ManifestSummaryData description: Compact summary of an errand's purchase manifest. AgentTaskSummaryData: properties: id: type: string title: Id status: type: string title: Status trigger_type: type: string title: Trigger Type workflow_run_id: anyOf: - type: string - type: 'null' title: Workflow Run Id task: anyOf: - type: string - type: 'null' title: Task title: anyOf: - type: string - type: 'null' title: Title started_at: anyOf: - type: integer - type: 'null' title: Started At completed_at: anyOf: - type: integer - type: 'null' title: Completed At created_at: type: integer title: Created At type: object required: - id - status - trigger_type - created_at title: AgentTaskSummaryData description: Lightweight summary of a UserAgentTask for IPA expand. IPACandidateData: properties: id: type: string title: Id offer_id: type: string title: Offer Id rank: anyOf: - type: integer - type: 'null' title: Rank score: anyOf: - type: number - type: 'null' title: Score status: type: string title: Status rejection_reason: anyOf: - type: string - type: 'null' title: Rejection Reason created_at: type: integer title: Created At type: object required: - id - offer_id - status - created_at title: IPACandidateData description: Candidate search result for an IPA. IPAManifestData: properties: id: type: string title: Id status: type: string title: Status total_amount: anyOf: - type: string - type: 'null' title: Total Amount total_asset: anyOf: - type: string - type: 'null' title: Total Asset approved_at: anyOf: - type: integer - type: 'null' title: Approved At purchased_at: anyOf: - type: integer - type: 'null' title: Purchased At items: items: $ref: '#/components/schemas/IPAManifestItemData' type: array title: Items created_at: type: integer title: Created At type: object required: - id - status - items - created_at title: IPAManifestData description: Purchase manifest for an IPA. IPAEventData: properties: id: type: string title: Id description: Identifier of the event. event_type: $ref: '#/components/schemas/IPAEventType' description: What happened to the errand. payload: anyOf: - type: string - type: 'null' title: Payload description: JSON-encoded detail attached to the event, when it carries any. created_at: type: integer title: Created At description: When the event was recorded. type: object required: - id - event_type - created_at title: IPAEventData EIP712Payload: properties: types: additionalProperties: items: additionalProperties: type: string type: object type: array type: object title: Types primaryType: type: string title: Primarytype domain: $ref: '#/components/schemas/EIP712DomainData' message: $ref: '#/components/schemas/EIP712PurchaseIntentMessage' type: object required: - types - primaryType - domain - message title: EIP712Payload ComparisonOp: type: string enum: - lte - gte - lt - gt - eq title: ComparisonOp description: >- How a value is compared against a target. `lte` is at most and `gte` is at least, both counting the target itself. `lt` is below and `gt` is above, both excluding it. `eq` matches the target exactly. MandateLimitStatus: type: string enum: - no_amount_authorized - headroom_unknown - headroom_known title: MandateLimitStatus description: >- Whether a mandate carries a spend limit, and whether what is left under it is known. `no_amount_authorized` — the mandate authorizes no amount, so there is no limit to report and nothing to measure spending in flight against. `headroom_unknown` — a limit is in force, but some spending against it could not be read, or could not be compared against that limit: either spending still in flight, or what has already settled. How much is still available cannot be worked out, and the amounts consumed and reserved are each a minimum rather than a whole. `headroom_known` — a limit is in force and every amount spent against it was counted, so the amount still available is a figure spending can be planned against. None of the three permits unlimited spending: a purchase is checked against the mandate when it is made, whatever this reports. IPAManifestItemData: properties: offer_id: type: string title: Offer Id quantity: type: integer title: Quantity unit_price_amount: type: string title: Unit Price Amount unit_price_asset: type: string title: Unit Price Asset type: object required: - offer_id - quantity - unit_price_amount - unit_price_asset title: IPAManifestItemData description: Line item within a purchase manifest. IPAEventType: type: string enum: - ipa.status_change - ipa.clarification_sent - ipa.clarification_received - ipa.approval_requested - ipa.approval_received - ipa.workflow_started - ipa.workflow_completed - ipa.workflow_failed - ipa.cancelled - ipa.workflow_resumed - ipa.monitor_started - ipa.price_checked - ipa.conditions_met - ipa.monitor_expired - ipa.monitor_reentry - ipa.pint_linked - ipa.card_instruction_opened - ipa.mandate_revoked title: IPAEventType EIP712DomainData: properties: name: type: string title: Name version: type: string title: Version chainId: type: integer title: Chainid verifyingContract: type: string title: Verifyingcontract type: object required: - name - version - chainId - verifyingContract title: EIP712DomainData EIP712PurchaseIntentMessage: properties: wallet: type: string title: Wallet nonce: type: integer title: Nonce statement: type: string title: Statement scopes: items: type: string type: array title: Scopes resources: items: type: string type: array title: Resources conditions: items: type: string type: array title: Conditions maxAmount: type: integer title: Maxamount maxAmountToken: type: string title: Maxamounttoken expiresAt: type: integer title: Expiresat type: object required: - wallet - nonce - statement - scopes - resources - maxAmount - maxAmountToken - expiresAt title: EIP712PurchaseIntentMessage securitySchemes: PintBearer: type: apiKey in: header name: x-sumvin-pint-token description: >- PINT (Purchase Intent) token — a JWT issued via `POST /v0/sis/token/pint` that encodes user-level consent for a specific scope. Sent in the `x-sumvin-pint-token` header alongside or instead of an `x-juno-jwt` JWT, depending on the integration surface (Platform vs SIS). SumvinPAT: type: apiKey in: header name: x-sumvin-pat description: >- Personal access token issued to the Sumvin CLI. Send it in the `x-sumvin-pat` header to authenticate as the owning user. ````