> ## 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. # Check mandate key setup > Report how far setting up the signed-in account holder's mandate key has got. The mandate key is the wallet key they sign spending mandates with; it can sign once it has been added as an owner of their smart wallet. `stage` is one of: - `not_provisioned`: there is no wallet key for this account yet. - `awaiting_claim`: the wallet key exists but must be claimed first. - `pending`: setup is under way. - `active`: the key can sign. - `failed`: the last attempt failed and may be retried; `error_code` and `error_reason` say why. - `blocked`: setup cannot proceed; `blocked_reason` says why. Only `active` is settled. While `pending`, check again every few seconds, and wait longer between attempts after a 429. Stop checking on `blocked` or `not_provisioned`, and claim the key on `awaiting_claim`. Call this from the account holder's own signed-in browser session. Personal access tokens, agent tokens and connector access tokens are refused. ## OpenAPI ````yaml /api-reference/openapi.json get /v0/user/me/mandate-key openapi: 3.1.0 info: title: Sumvin API version: 0.41.0 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 the user's wallets. Addresses registered as signers on the user's Safe are not wallets the account holder transacts from and are omitted; read one directly at `GET /v0/wallets/{wallet_id}` | | `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** | Safe smart account whose signer set holds the user's agent signer, and any other key registered against it | An address registered as a signer on the user's Safe is stored alongside these but is not one of them. It is omitted from list responses so they hold only wallets the account holder transacts from, it stays readable by its own wallet ID, and it cannot be deleted while it carries a signer role — removing the record would not remove the key from the Safe on chain. ## 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). Narrows the list; it does not reintroduce addresses registered as Safe signers | ## 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: Connected Agents description: > The AI agents a user has connected to their Sumvin account, and how they are disconnected. ## Overview Connecting an agent to a Sumvin account creates a key that belongs to that one connection. The key identifies the connection — it is what makes a connection individually recognisable and individually removable — and it is created the first time the connected agent calls Sumvin rather than at the moment of connecting. ## Capabilities - **List** - See every agent connected to the account, live or already disconnected - **Disconnect** - Remove one connection; its key is disabled and stops being honoured ## Who can call these Only the account owner, from the Sumvin app or the Sumvin CLI. A connected agent is refused, so no agent can list the account's other connections or disconnect itself or any of them. ## Disconnecting Disconnecting takes effect immediately: the connection's key is disabled and any access the agent was already holding stops working. Disconnecting an agent that is already disconnected succeeds and changes nothing. ## Related Resources - [Agent](#tag/Agent) - Token management for agents - 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/me/mandate-key: get: tags: - User summary: Check mandate key setup description: >- Report how far setting up the signed-in account holder's mandate key has got. The mandate key is the wallet key they sign spending mandates with; it can sign once it has been added as an owner of their smart wallet. `stage` is one of: - `not_provisioned`: there is no wallet key for this account yet. - `awaiting_claim`: the wallet key exists but must be claimed first. - `pending`: setup is under way. - `active`: the key can sign. - `failed`: the last attempt failed and may be retried; `error_code` and `error_reason` say why. - `blocked`: setup cannot proceed; `blocked_reason` says why. Only `active` is settled. While `pending`, check again every few seconds, and wait longer between attempts after a 429. Stop checking on `blocked` or `not_provisioned`, and claim the key on `awaiting_claim`. Call this from the account holder's own signed-in browser session. Personal access tokens, agent tokens and connector access tokens are refused. operationId: getUserMandateKey parameters: - name: chain_id in: query required: false schema: anyOf: - type: integer - type: 'null' description: >- Network to report on. Defaults to the account's primary network. A signing key is only set up on the primary network, so on another supported network it does not become `active` and usually reports `blocked`. A network the service does not operate on is a 400. title: Chain Id description: >- Network to report on. Defaults to the account's primary network. A signing key is only set up on the primary network, so on another supported network it does not become `active` and usually reports `blocked`. A network the service does not operate on is a 400. - name: x-juno-jwt in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Juno-Jwt - 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 - $ref: '#/components/parameters/XTimestampFormat' responses: '200': description: Where mandate key setup stands content: application/json: schema: $ref: '#/components/schemas/MandateKeyActivationResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ProblemDetail' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ProblemDetail' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '429': description: Too Many Requests content: application/json: schema: $ref: '#/components/schemas/ProblemDetail' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ProblemDetail' security: - JunoJWT: [] 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: MandateKeyActivationResponse: properties: _links: additionalProperties: $ref: '#/components/schemas/Link' type: object title: Links description: HAL-style hypermedia links for navigation and available actions. stage: $ref: '#/components/schemas/MandateKeyActivationStage' description: >- How far setup has got. `active` is the only settled stage: the key can sign. `pending`: setup is under way — check again every few seconds. `failed`: the last attempt failed and may be retried; `error_code` and `error_reason` say why. `blocked`: setup cannot proceed yet; `blocked_reason` says why — stop checking. `awaiting_claim`: the wallet key exists but has not been claimed; claim it first. `not_provisioned`: there is no wallet key for this account yet. blocked_reason: anyOf: - $ref: '#/components/schemas/MandateKeyBlockedReason' - type: 'null' description: >- Why setup cannot proceed, set only when `stage` is `blocked`. `activation_disabled`: mandate key setup is not available to this account. `kyc_not_verified`: identity verification is not complete. `chain_not_deployable`: a mandate key is never set up on the requested network. `safe_not_deployed`: the smart wallet has not been created yet. `address_conflict`: this key's address is already used on the account in another role. address: anyOf: - type: string - type: 'null' title: Address description: >- The mandate key's address, lowercased. Absent until a wallet key exists. chain_id: anyOf: - $ref: '#/components/schemas/DeployableChain' - type: 'null' description: >- The network this reading is for. Absent when the account has no network a smart wallet can be set up on. error_code: anyOf: - type: string - type: 'null' title: Error Code description: >- Machine-readable cause of the last failed attempt. Set only when `stage` is `failed`. error_reason: anyOf: - type: string - type: 'null' title: Error Reason description: >- Human-readable cause of the last failed attempt. Set only when `stage` is `failed`. type: object required: - _links - stage title: MandateKeyActivationResponse description: >- Where setting up the account holder's mandate key stands. The mandate key is the wallet key the account holder signs spending mandates with. Before it can sign, it has to be added as an owner of their smart wallet. examples: - _links: self: href: /v0/user/me/mandate-key stage: not_provisioned - _links: self: href: /v0/user/me/mandate-key address: '0x9f2c4e1a7b3d5c8e0f6a2b4d8c1e3f5a7b9d0c2e' chain_id: 1329 stage: awaiting_claim - _links: self: href: /v0/user/me/mandate-key address: '0x9f2c4e1a7b3d5c8e0f6a2b4d8c1e3f5a7b9d0c2e' chain_id: 1329 stage: pending - _links: self: href: /v0/user/me/mandate-key address: '0x9f2c4e1a7b3d5c8e0f6a2b4d8c1e3f5a7b9d0c2e' chain_id: 1329 stage: active - _links: self: href: /v0/user/me/mandate-key address: '0x9f2c4e1a7b3d5c8e0f6a2b4d8c1e3f5a7b9d0c2e' chain_id: 1329 error_code: SGN-422-002 error_reason: >- The account's Safe requires more than one signature, which is not supported. stage: failed - _links: self: href: /v0/user/me/mandate-key address: '0x9f2c4e1a7b3d5c8e0f6a2b4d8c1e3f5a7b9d0c2e' blocked_reason: kyc_not_verified chain_id: 1329 stage: blocked 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. _links: anyOf: - additionalProperties: $ref: '#/components/schemas/Affordance' type: object - type: 'null' title: Links description: >- Actions that clear this error, keyed by link relation. Present only on errors a caller can act on. 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), AID (connected agent), 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 (deployment-mode card), 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), MCP (Model Context Protocol), MCR (spending-mandate approval), MKY (mandate key), MLD (MELD), MRC (merchant search), OBK (open banking), ONB (onboarding), ORG (organisation), PAY (payment link), PAR (embedded-wallet provider webhook), 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 HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError 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. MandateKeyActivationStage: type: string enum: - not_provisioned - awaiting_claim - pending - active - failed - blocked title: MandateKeyActivationStage description: >- How far the account's signing key has got towards approving mandates. Only `active` is settled. `failed` means the last attempt to register the key did not complete and may be retried. `pending` means registration is under way or will start without further action. `blocked` means registration cannot start yet, and `blocked_reason` says why. `awaiting_claim` means the key exists and the account holder has not claimed it yet. `not_provisioned` means no key has been created yet. MandateKeyBlockedReason: type: string enum: - activation_disabled - kyc_not_verified - chain_not_deployable - safe_not_deployed - address_conflict title: MandateKeyBlockedReason description: >- Why the signing key's registration cannot start yet. `address_conflict` means the key's address is already one of the account's own wallets, so it is not registered as a signer. DeployableChain: type: integer enum: - 1329 - 1328 title: DeployableChain description: |- Chains where a user's Safe and signer can be deployed. Narrower than `KnownChains` (the asset / ramp universe). Only chains the on-chain workers (safe-creation, signer-deployment) actually support deployment to. `SEI_TESTNET` is accepted in non-production environments only — gated by `validate_deployable_chain_for_env`. - `1329` - Sei mainnet (the operational chain on prod-uc1) - `1328` - Sei testnet (non-production only) APIErrorCode: type: string enum: - USR-208-001 - USR-404-001 - USR-401-001 - USR-401-002 - USR-400-001 - USR-424-001 - USR-500-001 - USR-409-003 - 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 - WAL-403-005 - WAL-403-006 - 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-400-005 - KYC-404-002 - KYC-409-005 - KYC-409-006 - KYC-403-003 - KYC-410-001 - KYC-429-001 - KYC-503-001 - KYC-403-004 - KYC-429-002 - KYC-503-002 - KYC-422-001 - MCR-400-001 - MCR-422-001 - MCR-422-002 - MCR-422-003 - MCR-403-001 - MCR-404-001 - MCR-409-001 - MCR-409-002 - MCR-409-003 - MCR-410-001 - MCR-401-001 - MCR-401-002 - MCR-401-003 - MCR-401-004 - MCR-401-005 - MCR-503-002 - MCR-429-001 - MCR-503-001 - MCR-400-002 - MCR-500-001 - MKY-429-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 - SGN-409-001 - SGN-429-001 - SGN-403-001 - SGN-403-002 - SGN-422-002 - SGN-422-003 - SGN-424-001 - SGN-424-002 - SGN-502-005 - SGN-502-006 - SGN-502-007 - SGN-503-001 - SGN-500-003 - 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-409-003 - PHONE-503-001 - 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 - PAR-401-001 - PAR-409-001 - PAR-502-001 - PAR-502-002 - PAR-503-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 - AID-403-001 - AID-404-001 - AID-503-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-400-008 - PINT-400-009 - PINT-401-001 - PINT-401-002 - PINT-401-005 - PINT-401-007 - PINT-401-008 - PINT-401-009 - 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-409-008 - PINT-410-001 - PINT-410-002 - PINT-424-001 - PINT-424-002 - PINT-424-003 - PINT-424-005 - PINT-424-006 - PINT-424-007 - PINT-503-001 - PINT-500-002 - 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-403-009 - PINT-409-006 - PINT-409-007 - 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-403-002 - IPA-401-001 - IPA-401-002 - IPA-401-003 - IPA-401-004 - IPA-401-005 - IPA-409-002 - IPA-409-003 - IPA-422-001 - IPA-503-001 - IPA-400-003 - IPA-500-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-403-002 - CLI-404-001 - CLI-409-001 - CLI-410-001 - CLI-503-001 - CALLER-400-001 - CALLER-403-001 - CALLER-503-001 - MCP-401-001 - MCP-403-001 - MCP-403-002 - MCP-429-001 - MCP-429-002 - 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 - MCP-503-001 - TAP-503-001 - TAP-502-001 - TAP-421-001 - GEN-400-001 - SYS-500-001 title: APIErrorCode Affordance: properties: rel: type: string title: Rel description: >- Link relation naming what this action is for, e.g. 'verify'. Used as the key under _links. href: type: string title: Href description: URL a client follows to take this action. method: type: string title: Method description: >- HTTP method to use when following href. GET to read, POST/PUT/DELETE to act. default: GET description: type: string title: Description description: >- What taking this action achieves, phrased so it reads inside a sentence. tool: anyOf: - type: string - type: 'null' title: Tool description: >- Name of the tool that performs this action for callers on the Model Context Protocol lane. Absent when the action has no tool. payload: anyOf: - additionalProperties: true type: object - type: 'null' title: Payload description: >- Arguments to pass to the named tool. Absent when the tool takes none. type: object required: - rel - href - description title: Affordance description: >- One next action a refused caller can take, described for either lane. An error that only says *no* leaves the caller to guess. This carries the move that clears the refusal, in the two vocabularies the two callers speak: a REST client follows ``href`` with ``method``, and an agent on the Model Context Protocol lane calls ``tool`` with ``payload``. Both describe the same action, so a nudge cannot go stale on one lane while it is maintained on the other. ``tool`` and ``payload`` are optional because not every action is reachable from an agent — a page a person has to open in a browser has a route and no tool. Such an affordance still renders in the HAL body and is simply absent from what the agent is told to do, which is honest rather than misleading. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError securitySchemes: JunoJWT: type: apiKey in: header name: x-juno-jwt description: >- Session JWT from the identity provider that signed the user in — Dynamic Labs, Privy, or Clerk (consumer sign-in). Send it in the `x-juno-jwt` header on every authenticated request. An `Authorization: Bearer ` header carrying the same JWT is also accepted, and takes precedence when both are present. ````