{ "openapi": "3.1.0", "info": { "title": "Hitch Partner API", "version": "1.0.0", "summary": "Hitch Partner API for NEAR Intents trading integrations.", "description": "The Hitch Partner API wraps account verification, copy-trading coordination, and optional Hitch-managed 1Click execution.\n\n## Wallet verification\n\nThe partner DEX or wallet connects and creates the signer. Hitch does not create wallets or passkeys. To verify an existing signer, call POST /wallet-challenge, have the connected client sign the exact challenge (or complete a WebAuthn assertion), then send that proof to POST /verify-wallet. WalletConnect is a client-side transport: use walletType evm or solana according to the connected namespace. Passkeys are supported for verification; the client performs navigator.credentials.get().\n\nThe successful verification response sets a role-scoped HttpOnly cookie for a browser client. When the request is authenticated with a partner key, the response also returns a short-lived user session token for server-to-server calls. A Hitch partner key is never a user wallet credential.\n\n## Execution modes\n\n**Hitch-managed:** Hitch uses its server-side 1Click credential for quote, signing payload creation, submission, and status. The Hitch 1Click JWT is never returned.\n\n**Partner-managed:** the partner keeps its own 1Click JWT and calls 1Click directly. For deposits, Hitch returns the normalized quote request and the partner obtains its own live quote. For copy trades, POST /copy-trades/get-quote returns a dry combined estimate. Then POST /copy-trades/prepare creates the escrow and returns the final live quote request. The partner obtains a live quote with its own JWT and sends the exact request and signed 1Click response to POST /copy-trades/submit. Hitch validates that handoff, returns the Leader contribution intent for signature, then accepts that signature on a second submit call. Hitch's escrow key signs and submits the final transfer to the 1Click deposit address; the partner never needs the escrow private key.\n\n## Copy-trade allocation\n\nFor EXACT_INPUT, leaderAmountIn is the Leader's input; eligible Followers contribute according to their available balances and the combined source input is quoted. For EXACT_OUTPUT, combinedAmountOut is the fixed total destination output. Hitch splits the required source input among the Leader and eligible Followers in proportion to available balances, subject to each participant's available balance and the $1 minimum. At settlement, the fixed output is distributed back to the Leader and contributing Followers in proportion to their confirmed source contributions; the Leader's fee is deducted from follower shares. Estimates can change before execution as balances and live quotes are refreshed.\n\n## Credentials\n\nPartner API keys are issued through Hitch's restricted admin panel and are sent only from a partner server in the X-Partner-Api-Key header. The raw key is shown once; Never put a partner key in browser or mobile code. The user session is scoped to a verified Intents account and role. Keep wallet signatures in the client until an operation endpoint requests the signed payload; never send private keys or seed phrases.\n\nFor first-party browser clients, requests use the role-scoped Hitch session cookie and X-Hitch-Role header. Partner server requests use the partner API key and user session bearer token.\n\n## Upstream protocol references\n\n- [1Click quote request and response fields](https://docs.near-intents.org/api-reference/oneclick/request-a-swap-quote)\n- [1Click quote signature verification](https://docs.near-intents.org/integration/distribution-channels/1click-api/verify-quote-signature)\n- [NEAR Intents account abstraction](https://docs.near-intents.org/integration/verifier-contract/account-abstraction)\n- [NEAR Intents signing formats](https://docs.near-intents.org/integration/distribution-channels/1click-api/quickstart/signed-intent-execution)", "contact": { "name": "Hitch API team", "url": "https://hitch.fi" }, "license": { "name": "Proprietary" }, "x-hitch-contract-status": "production" }, "servers": [ { "url": "https://api.hitch.fi/v1", "description": "Production API base URL." }, { "url": "http://localhost:3001/v1", "description": "Local development server." } ], "tags": [ { "name": "Wallet sessions", "description": "Prove wallet control and obtain an account-scoped user session." }, { "name": "Accounts", "description": "Resolve deterministic Intents account identity and read balances." }, { "name": "Assets", "description": "Canonical Intents assets supported by Hitch." }, { "name": "Deposits", "description": "Prepare and track source-chain deposits to an Intents account." }, { "name": "Leaders", "description": "Register leaders, manage fees, and inspect follower relationships." }, { "name": "Follows", "description": "Prepare and confirm explicit follower key delegation and fee consent." }, { "name": "Single swaps", "description": "Hitch-managed standalone quote and swap operations." }, { "name": "Copy trading", "description": "Dry estimate, final quote handoff, execution, and history." } ], "security": [ { "PartnerApiKey": [] } ], "paths": { "/account": { "get": { "tags": [ "Accounts" ], "operationId": "getCurrentAccount", "summary": "Get the verified Intents account", "description": "Returns the account derived from the current verified user session. An Intents account ID is derived from the signer's public identity; it is not created by inserting an account row on-chain.", "x-hitch-status": "implemented locally", "security": [ { "PartnerApiKey": [], "UserSession": [] }, { "LeaderSessionCookie": [] }, { "FollowerSessionCookie": [] } ], "responses": { "200": { "description": "Current account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrentAccount" }, "example": { "accountId": "0xdbd37cede8c61ccfde77281670d79660519a0967", "walletType": "passkey", "walletAddress": "p256:39BmkNbgbHwBuDFnwjRRztHT8RqznwJwxTeCiY7AmGMjHmhPixoDgMqxz1f6fLjqgRJJtVTg3zS8kgh7UBCvv2LC", "role": "follower", "verifiedAt": "2026-10-08T12:00:00.000Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/account/balances": { "get": { "tags": [ "Accounts" ], "operationId": "getBalances", "summary": "Get current account balances", "description": "Reads only the account owned by the verified user session. Amounts are decimal strings in token base units; `decimals` defines display conversion. Balance authorization must be completed separately and is read only.", "x-hitch-status": "implemented locally", "security": [ { "PartnerApiKey": [], "UserSession": [] }, { "LeaderSessionCookie": [] }, { "FollowerSessionCookie": [] } ], "parameters": [ { "name": "assetId", "in": "query", "required": false, "description": "Optional canonical asset ID filter.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Balance snapshot.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceList" }, "example": { "accountId": "0x5870000000000000000000000000000019b5", "asOf": "2026-10-08T12:02:15.000Z", "balances": [ { "assetId": "nep141:wrap.near", "symbol": "NEAR", "decimals": 24, "amount": "790617773472457270383416", "formattedAmount": "0.790617773472457270383416" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "428": { "$ref": "#/components/responses/PreconditionRequired" } } } }, "/assets": { "get": { "tags": [ "Assets" ], "operationId": "getAssets", "summary": "List supported assets", "description": "Returns the shared asset catalog built from 1Click's supported-token list. Canonical Intents representations are used for swaps and copy trades; each asset also lists matching external-network source representations for deposits, with source price freshness. Asset IDs, not tickers, identify assets. A ticker such as NEAR can have different representations on different networks.", "x-hitch-status": "implemented locally", "responses": { "200": { "description": "Supported asset catalog.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetList" }, "example": { "assets": [ { "assetId": "nep141:wrap.near", "symbol": "NEAR", "name": "NEAR", "decimals": 24, "network": "near", "canonical": true, "priceUsd": "5.04", "priceUpdatedAt": "2026-10-08T12:00:00.000Z", "sources": [] }, { "assetId": "nep141:usdc.near", "symbol": "USDC", "name": "USD Coin", "decimals": 6, "network": "near", "canonical": true, "priceUsd": "1.00", "priceUpdatedAt": "2026-10-08T12:00:00.000Z", "sources": [ { "assetId": "nep141:usdc.e", "network": "eth", "symbol": "USDC", "decimals": 6, "priceUsd": "1.00", "priceUpdatedAt": "2026-10-08T12:00:00.000Z", "priceFresh": true } ] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "security": [ { "PartnerApiKey": [] }, {} ] } }, "/deposit/submit": { "post": { "tags": [ "Deposits" ], "operationId": "createDepositQuote", "summary": "Prepare a deposit using an asset, network, and amount", "description": "Prepares a deposit quote from an external source network into the verified Intents account. Partner-managed integrations must provide amount and receive a quote request template to quote with their own 1Click JWT. Hitch-managed integrations receive a live quote. Only the local first-party Hitch-managed form may omit amount to create a flexible minimum-deposit address. Hitch quoteId and 1Click correlationId are separate references.", "x-hitch-status": "implemented locally", "security": [ { "PartnerApiKey": [], "UserSession": [] }, { "LeaderSessionCookie": [] }, { "FollowerSessionCookie": [] } ], "requestBody": { "$ref": "#/components/requestBodies/DepositQuoteRequest" }, "responses": { "200": { "description": "Partner-managed 1Click quote request template.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DepositQuoteResult" } } } }, "201": { "description": "Hitch-managed live deposit quote.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DepositQuoteResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" } } } }, "/deposit/get": { "get": { "tags": [ "Deposits" ], "operationId": "getDepositStatus", "summary": "Get deposit quote and settlement status", "description": "Returns the provider-reported deposit status for this user's quote. Pass the Hitch-generated quoteId as a query parameter. `SUCCESS` is not a substitute for refreshing and reconciling the Intents balance.", "x-hitch-status": "implemented locally", "security": [ { "PartnerApiKey": [], "UserSession": [] }, { "LeaderSessionCookie": [] }, { "FollowerSessionCookie": [] } ], "parameters": [ { "$ref": "#/components/parameters/QuoteId" } ], "responses": { "200": { "description": "Current provider state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DepositStatus" }, "example": { "status": "PROCESSING", "updatedAt": "2026-10-09T12:04:00.000Z", "transactionHashes": [ { "hash": "0xabc123_example", "explorerUrl": "https://explorer.example/tx/0xabc123_example" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/leaders": { "get": { "tags": [ "Leaders" ], "operationId": "getLeaders", "summary": "List registered leaders", "description": "Returns public leader account IDs, fee rates, and activity counts. It does not return follower balances or private trade data.", "x-hitch-status": "implemented locally", "responses": { "200": { "description": "Leader page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaderList" }, "example": { "leaders": [ { "accountId": "0x5870000000000000000000000000000019b5", "blockchain": "base", "copyTradingFeeBps": 10, "copyTradingFeeVersion": 1, "followerCount": 3, "successfulTradeCount": 14, "createdAt": "2026-10-01T12:00:00.000Z" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [ { "PartnerApiKey": [] }, {} ] } }, "/swaps/get-quote": { "post": { "tags": [ "Single swaps" ], "operationId": "getSwapQuote", "summary": "Quote a standalone Intents swap", "description": "Gets a dry or live single-account 1Click quote. Set dry true to preview/poll; set false to receive the operation-specific unsigned intent. The destination and refund account are always the verified Intents account and the execution mode is Hitch-managed. Hitch creates quoteId; correlationId comes from 1Click.", "x-hitch-status": "implemented locally", "security": [ { "PartnerApiKey": [], "UserSession": [] }, { "LeaderSessionCookie": [] }, { "FollowerSessionCookie": [] } ], "requestBody": { "$ref": "#/components/requestBodies/SingleQuoteRequest" }, "responses": { "200": { "description": "Individual 1Click quote and the normalized request sent to the provider.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SingleQuoteResult" }, "examples": { "exactInputDry": { "summary": "Dry quote for an exact input", "value": { "quoteId": "550e8400-e29b-41d4-a716-446655440011", "executionMode": "hitch-managed", "amountIn": "1000000", "amountOut": "995000000000000000000000", "minAmountOut": "985000000000000000000000", "expectedFee": { "amount": "0", "assetId": "nep141:wrap.near", "symbol": "NEAR", "decimals": 24 }, "slippageToleranceBps": 100, "deadline": "2026-10-08T13:00:00.000Z", "appFees": [], "quoteRequest": { "dry": true, "swapType": "EXACT_INPUT", "originAsset": "nep141:usdc.near", "destinationAsset": "nep141:wrap.near", "amount": "1000000", "recipient": "0x5870000000000000000000000000000019b5", "recipientType": "CONFIDENTIAL_INTENTS", "refundTo": "0x5870000000000000000000000000000019b5", "refundType": "CONFIDENTIAL_INTENTS", "slippageTolerance": 100, "deadline": "2026-10-08T13:00:00.000Z", "appFees": [], "depositType": "CONFIDENTIAL_INTENTS", "connectedWallets": [ "0x1111111111111111111111111111111111111111" ], "sessionId": "hitch_550e8400-e29b-41d4-a716-446655440031", "confidentiality": "basic", "referral": "hitch", "depositMode": "SIMPLE" }, "quoteResponse": { "signature": "example_provider_signature", "quote": { "amountIn": "1000000", "amountOut": "995000000000000000000000", "minAmountOut": "985000000000000000000000" }, "correlationId": "550e8400-e29b-41d4-a716-446655440000", "timestamp": "2026-10-08T12:00:00.000Z", "quoteRequest": { "dry": true, "swapType": "EXACT_INPUT", "originAsset": "nep141:usdc.near", "destinationAsset": "nep141:wrap.near", "amount": "1000000", "recipient": "0x5870000000000000000000000000000019b5", "recipientType": "CONFIDENTIAL_INTENTS", "refundTo": "0x5870000000000000000000000000000019b5", "refundType": "CONFIDENTIAL_INTENTS", "slippageTolerance": 100, "deadline": "2026-10-08T13:00:00.000Z", "appFees": [], "depositType": "CONFIDENTIAL_INTENTS", "connectedWallets": [ "0x1111111111111111111111111111111111111111" ], "sessionId": "hitch_550e8400-e29b-41d4-a716-446655440031", "confidentiality": "basic", "referral": "hitch", "depositMode": "SIMPLE" } }, "swapType": "EXACT_INPUT" } }, "exactOutputDry": { "summary": "Dry quote for an exact output", "value": { "quoteId": "550e8400-e29b-41d4-a716-446655440012", "executionMode": "hitch-managed", "amountIn": "5050000", "amountOut": "1000000000000000000000000", "expectedFee": { "amount": "0", "assetId": "nep141:wrap.near", "symbol": "NEAR", "decimals": 24 }, "slippageToleranceBps": 100, "deadline": "2026-10-08T13:00:00.000Z", "appFees": [], "quoteRequest": { "dry": true, "swapType": "EXACT_OUTPUT", "originAsset": "nep141:usdc.near", "destinationAsset": "nep141:wrap.near", "amount": "1000000000000000000000000", "recipient": "0x5870000000000000000000000000000019b5", "recipientType": "CONFIDENTIAL_INTENTS", "refundTo": "0x5870000000000000000000000000000019b5", "refundType": "CONFIDENTIAL_INTENTS", "slippageTolerance": 100, "deadline": "2026-10-08T13:00:00.000Z", "appFees": [], "depositType": "CONFIDENTIAL_INTENTS", "connectedWallets": [ "0x1111111111111111111111111111111111111111" ], "sessionId": "hitch_550e8400-e29b-41d4-a716-446655440031", "confidentiality": "basic", "referral": "hitch", "depositMode": "SIMPLE" }, "quoteResponse": { "signature": "example_provider_signature", "quote": { "amountIn": "5050000", "amountOut": "1000000000000000000000000", "minAmountIn": "5000000" }, "correlationId": "550e8400-e29b-41d4-a716-446655440002", "timestamp": "2026-10-08T12:00:00.000Z", "quoteRequest": { "dry": true, "swapType": "EXACT_OUTPUT", "originAsset": "nep141:usdc.near", "destinationAsset": "nep141:wrap.near", "amount": "1000000000000000000000000", "recipient": "0x5870000000000000000000000000000019b5", "recipientType": "CONFIDENTIAL_INTENTS", "refundTo": "0x5870000000000000000000000000000019b5", "refundType": "CONFIDENTIAL_INTENTS", "slippageTolerance": 100, "deadline": "2026-10-08T13:00:00.000Z", "appFees": [], "depositType": "CONFIDENTIAL_INTENTS", "connectedWallets": [ "0x1111111111111111111111111111111111111111" ], "sessionId": "hitch_550e8400-e29b-41d4-a716-446655440031", "confidentiality": "basic", "referral": "hitch", "depositMode": "SIMPLE" } }, "swapType": "EXACT_OUTPUT", "minAmountIn": "5000000" } }, "exactInputLive": { "summary": "Live quote for an exact input", "value": { "quoteId": "550e8400-e29b-41d4-a716-446655440013", "executionMode": "hitch-managed", "amountIn": "1000000", "amountOut": "995000000000000000000000", "minAmountOut": "985000000000000000000000", "expectedFee": { "amount": "0", "assetId": "nep141:wrap.near", "symbol": "NEAR", "decimals": 24 }, "slippageToleranceBps": 100, "deadline": "2026-10-08T13:00:00.000Z", "appFees": [], "quoteRequest": { "dry": false, "swapType": "EXACT_INPUT", "originAsset": "nep141:usdc.near", "destinationAsset": "nep141:wrap.near", "amount": "1000000", "recipient": "0x5870000000000000000000000000000019b5", "recipientType": "CONFIDENTIAL_INTENTS", "refundTo": "0x5870000000000000000000000000000019b5", "refundType": "CONFIDENTIAL_INTENTS", "slippageTolerance": 100, "deadline": "2026-10-08T13:00:00.000Z", "appFees": [], "depositType": "CONFIDENTIAL_INTENTS", "connectedWallets": [ "0x1111111111111111111111111111111111111111" ], "sessionId": "hitch_550e8400-e29b-41d4-a716-446655440031", "confidentiality": "basic", "referral": "hitch", "depositMode": "SIMPLE" }, "quoteResponse": { "signature": "example_provider_signature", "quote": { "amountIn": "1000000", "amountOut": "995000000000000000000000", "minAmountOut": "985000000000000000000000", "depositAddress": "0xdeposit_single_exact_input", "deadline": "2026-10-08T13:00:00.000Z" }, "correlationId": "550e8400-e29b-41d4-a716-446655440000", "timestamp": "2026-10-08T12:00:00.000Z", "quoteRequest": { "dry": false, "swapType": "EXACT_INPUT", "originAsset": "nep141:usdc.near", "destinationAsset": "nep141:wrap.near", "amount": "1000000", "recipient": "0x5870000000000000000000000000000019b5", "recipientType": "CONFIDENTIAL_INTENTS", "refundTo": "0x5870000000000000000000000000000019b5", "refundType": "CONFIDENTIAL_INTENTS", "slippageTolerance": 100, "deadline": "2026-10-08T13:00:00.000Z", "appFees": [], "depositType": "CONFIDENTIAL_INTENTS", "connectedWallets": [ "0x1111111111111111111111111111111111111111" ], "sessionId": "hitch_550e8400-e29b-41d4-a716-446655440031", "confidentiality": "basic", "referral": "hitch", "depositMode": "SIMPLE" } }, "swapType": "EXACT_INPUT" } }, "exactOutputLive": { "summary": "Live quote for an exact output", "value": { "quoteId": "550e8400-e29b-41d4-a716-446655440014", "executionMode": "hitch-managed", "amountIn": "5050000", "amountOut": "1000000000000000000000000", "expectedFee": { "amount": "0", "assetId": "nep141:wrap.near", "symbol": "NEAR", "decimals": 24 }, "slippageToleranceBps": 100, "deadline": "2026-10-08T13:00:00.000Z", "appFees": [], "quoteRequest": { "dry": false, "swapType": "EXACT_OUTPUT", "originAsset": "nep141:usdc.near", "destinationAsset": "nep141:wrap.near", "amount": "1000000000000000000000000", "recipient": "0x5870000000000000000000000000000019b5", "recipientType": "CONFIDENTIAL_INTENTS", "refundTo": "0x5870000000000000000000000000000019b5", "refundType": "CONFIDENTIAL_INTENTS", "slippageTolerance": 100, "deadline": "2026-10-08T13:00:00.000Z", "appFees": [], "depositType": "CONFIDENTIAL_INTENTS", "connectedWallets": [ "0x1111111111111111111111111111111111111111" ], "sessionId": "hitch_550e8400-e29b-41d4-a716-446655440031", "confidentiality": "basic", "referral": "hitch", "depositMode": "SIMPLE" }, "quoteResponse": { "signature": "example_provider_signature", "quote": { "amountIn": "5050000", "amountOut": "1000000000000000000000000", "minAmountIn": "5000000", "depositAddress": "0xdeposit_single_exact_output", "deadline": "2026-10-08T13:00:00.000Z" }, "correlationId": "550e8400-e29b-41d4-a716-446655440002", "timestamp": "2026-10-08T12:00:00.000Z", "quoteRequest": { "dry": false, "swapType": "EXACT_OUTPUT", "originAsset": "nep141:usdc.near", "destinationAsset": "nep141:wrap.near", "amount": "1000000000000000000000000", "recipient": "0x5870000000000000000000000000000019b5", "recipientType": "CONFIDENTIAL_INTENTS", "refundTo": "0x5870000000000000000000000000000019b5", "refundType": "CONFIDENTIAL_INTENTS", "slippageTolerance": 100, "deadline": "2026-10-08T13:00:00.000Z", "appFees": [], "depositType": "CONFIDENTIAL_INTENTS", "connectedWallets": [ "0x1111111111111111111111111111111111111111" ], "sessionId": "hitch_550e8400-e29b-41d4-a716-446655440031", "confidentiality": "basic", "referral": "hitch", "depositMode": "SIMPLE" } }, "swapType": "EXACT_OUTPUT", "minAmountIn": "5000000" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" } } } }, "/swaps/submit": { "post": { "tags": [ "Single swaps" ], "operationId": "submitSingleSwap", "summary": "Submit a signed standalone swap", "description": "Submit the exact signed intent returned by a live quote. Use Hitch quoteId, not 1Click correlationId, with the stable idempotencyKey. Poll the returned swapId at GET /swaps/{swapId}; a 202 means processing, not settlement.", "x-hitch-status": "implemented locally", "security": [ { "PartnerApiKey": [], "UserSession": [] }, { "LeaderSessionCookie": [] }, { "FollowerSessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "quoteId", "signedIntent", "idempotencyKey" ], "properties": { "quoteId": { "type": "string", "description": "Hitch quote ID being accepted." }, "signedIntent": { "$ref": "#/components/schemas/SignedIntent", "description": "Exact signature over the generated intent payload for this quote." }, "idempotencyKey": { "type": "string", "minLength": 16, "maxLength": 128, "description": "Client-generated stable key preventing duplicate swap creation on retries." } }, "additionalProperties": false }, "example": { "quoteId": "550e8400-e29b-41d4-a716-446655440015", "signedIntent": { "standard": "nep413", "payload": { "recipient": "intents.near", "nonce": "AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8=", "message": "{\"signer_id\":\"0x5870000000000000000000000000000019b5\",\"verifying_contract\":\"intents.near\",\"deadline\":\"2026-10-08T13:00:00.000Z\",\"nonce\":\"AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8=\",\"intents\":[{\"intent\":\"swap_transfer\"}]}" }, "public_key": "ed25519:ExamplePublicKeyBase58", "signature": "ed25519:ExampleSignatureBase58" }, "idempotencyKey": "swap_20261008_user123_001" } } } }, "responses": { "202": { "description": "Swap accepted for reconciliation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Swap" }, "example": { "swapId": "swp_01J9H8", "status": "PROCESSING", "sourceAssetId": "nep141:usdc.near", "amountIn": "1000000", "destinationAssetId": "nep141:wrap.near", "estimatedAmountOut": "995000000000000000000000", "minAmountOut": "985000000000000000000000", "submittedAt": "2026-10-08T12:08:00.000Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/swaps/{swapId}": { "get": { "tags": [ "Single swaps" ], "operationId": "getSingleSwap", "summary": "Get swap status", "description": "Returns the provider and balance-reconciled status for the caller's swap.", "x-hitch-status": "implemented locally", "security": [ { "PartnerApiKey": [], "UserSession": [] }, { "LeaderSessionCookie": [] }, { "FollowerSessionCookie": [] } ], "parameters": [ { "name": "swapId", "in": "path", "required": true, "description": "Hitch swap ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Swap record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Swap" }, "example": { "swapId": "swp_01J9H8", "status": "SUCCESS", "sourceAssetId": "nep141:usdc.near", "amountIn": "1000000", "destinationAssetId": "nep141:wrap.near", "estimatedAmountOut": "995000000000000000000000", "settledAmountOut": "997000000000000000000000", "updatedAt": "2026-10-08T12:09:00.000Z", "minAmountOut": "985000000000000000000000", "submittedAt": "2026-10-08T12:08:00.000Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/copy-trades": { "get": { "tags": [ "Copy trading" ], "operationId": "getTrades", "summary": "List the current account's trade history", "description": "Lists the authenticated account’s copy-trade history. The cursor is opaque: pass back the exact nextCursor value from the previous response; omit it on the first page.", "x-hitch-status": "implemented locally", "security": [ { "PartnerApiKey": [], "UserSession": [] }, { "LeaderSessionCookie": [] }, { "FollowerSessionCookie": [] } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned by the prior page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Trade history page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CopyTradeList" }, "example": { "items": [ { "tradeId": "550e8400-e29b-41d4-a716-446655440021", "status": "SUCCESS", "role": "LEADER", "sourceAssetId": "nep141:wrap.near", "sourceDecimals": 24, "sourceContribution": "407706057266639649073549", "destinationAssetId": "nep141:usdc.near", "destinationDecimals": 6, "settledOutput": "4051200", "refundAllocation": null, "confirmedRefund": null, "createdAt": "2026-10-08T12:06:00.000Z" } ], "nextCursor": null, "refreshableTrades": [] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/copy-trades/get-quote": { "post": { "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "tags": [ "Copy trading" ], "operationId": "getCopyTradeQuote", "summary": "Get a combined Leader-and-Follower quote", "description": "Returns a dry combined 1Click quote for the Leader and eligible Follower contributions. This route currently requires dry: true because the final recipient must be the unique escrow created by POST /copy-trades/prepare. Use EXACT_INPUT with leaderAmountIn, or EXACT_OUTPUT with combinedAmountOut. EXACT_OUTPUT fixes the total destination amount; Hitch allocates required source input by available balances and distributes settled output by confirmed contribution shares. The full dry 1Click request and response are returned. For partner-managed execution, prepare the quote, obtain a non-dry 1Click quote using the returned escrow-bound request and the partner JWT, then submit the signed provider response to POST /copy-trades/submit.", "x-hitch-status": "implemented locally", "security": [ { "PartnerApiKey": [], "UserSession": [] }, { "LeaderSessionCookie": [] } ], "requestBody": { "$ref": "#/components/requestBodies/CopyTradeQuoteRequest" }, "responses": { "200": { "description": "Pooled quote, participant estimates, and the normalized request and response sent to 1Click.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CopyTradeQuote" }, "examples": { "exactInputDry": { "summary": "Combined dry quote for an exact input", "value": { "quoteId": "550e8400-e29b-41d4-a716-446655440016", "executionMode": "partner-managed", "feeBps": 10, "sourceAsset": { "assetId": "nep141:wrap.near", "symbol": "NEAR", "decimals": 24 }, "destinationAsset": { "assetId": "nep141:usdc.near", "symbol": "USDC", "decimals": 6 }, "leader": { "amountIn": "407706057266639649073549", "estimatedAmountOut": "4049800", "minAmountOut": "4009300" }, "followers": { "eligibleCount": 1, "excludedCount": 0, "amountIn": "808200000000000000000000", "estimatedGrossOutput": "2065800" }, "combined": { "amountIn": "1215906057266639649073549", "estimatedAmountOut": "6115600", "minAmountOut": "6054400", "quoteRequest": { "dry": true, "swapType": "EXACT_INPUT", "originAsset": "nep141:wrap.near", "destinationAsset": "nep141:usdc.near", "amount": "1215906057266639649073549", "recipient": "0xescrow_example", "recipientType": "CONFIDENTIAL_INTENTS", "refundTo": "0xescrow_example", "refundType": "CONFIDENTIAL_INTENTS", "slippageTolerance": 100, "deadline": "2026-10-08T13:00:00.000Z", "appFees": [], "depositType": "CONFIDENTIAL_INTENTS", "connectedWallets": [ "0x1111111111111111111111111111111111111111" ], "sessionId": "hitch_550e8400-e29b-41d4-a716-446655440031", "confidentiality": "basic", "referral": "hitch", "depositMode": "SIMPLE" }, "quoteResponse": { "signature": "example_provider_signature", "quote": { "amountIn": "1215906057266639649073549", "amountOut": "6115600", "minAmountOut": "6054400" }, "correlationId": "550e8400-e29b-41d4-a716-446655440000", "timestamp": "2026-10-08T12:00:00.000Z", "quoteRequest": { "dry": true, "swapType": "EXACT_INPUT", "originAsset": "nep141:wrap.near", "destinationAsset": "nep141:usdc.near", "amount": "1215906057266639649073549", "recipient": "0xescrow_example", "recipientType": "CONFIDENTIAL_INTENTS", "refundTo": "0xescrow_example", "refundType": "CONFIDENTIAL_INTENTS", "slippageTolerance": 100, "deadline": "2026-10-08T13:00:00.000Z", "appFees": [], "depositType": "CONFIDENTIAL_INTENTS", "connectedWallets": [ "0x1111111111111111111111111111111111111111" ], "sessionId": "hitch_550e8400-e29b-41d4-a716-446655440031", "confidentiality": "basic", "referral": "hitch", "depositMode": "SIMPLE" } } }, "expectedFee": { "amount": "2065", "assetId": "nep141:usdc.near", "symbol": "USDC", "decimals": 6, "rounding": "down to the destination asset's smallest unit" }, "expiresAt": "2026-10-08T12:05:00.000Z", "nextStep": "For partner-managed execution, request a non-dry 1Click quote for the combined amount using your JWT, then generate and sign the operation-specific intent.", "swapType": "EXACT_INPUT" } }, "exactOutputDry": { "summary": "Combined dry quote for an exact output", "value": { "quoteId": "550e8400-e29b-41d4-a716-446655440017", "executionMode": "partner-managed", "feeBps": 10, "sourceAsset": { "assetId": "nep141:wrap.near", "symbol": "NEAR", "decimals": 24 }, "destinationAsset": { "assetId": "nep141:usdc.near", "symbol": "USDC", "decimals": 6 }, "leader": { "amountIn": "400000000000000000000000", "estimatedAmountOut": "2000000", "minAmountIn": "396000000000000000000000" }, "followers": { "eligibleCount": 1, "excludedCount": 0, "amountIn": "400000000000000000000000", "estimatedGrossOutput": "2000000" }, "combined": { "amountIn": "800000000000000000000000", "estimatedAmountOut": "4000000", "quoteRequest": { "dry": true, "swapType": "EXACT_OUTPUT", "originAsset": "nep141:wrap.near", "destinationAsset": "nep141:usdc.near", "amount": "4000000", "recipient": "0xescrow_example", "recipientType": "CONFIDENTIAL_INTENTS", "refundTo": "0xescrow_example", "refundType": "CONFIDENTIAL_INTENTS", "slippageTolerance": 100, "deadline": "2026-10-08T13:00:00.000Z", "appFees": [], "depositType": "CONFIDENTIAL_INTENTS", "connectedWallets": [ "0x1111111111111111111111111111111111111111" ], "sessionId": "hitch_550e8400-e29b-41d4-a716-446655440031", "confidentiality": "basic", "referral": "hitch", "depositMode": "SIMPLE" }, "quoteResponse": { "signature": "example_provider_signature", "quote": { "amountIn": "800000000000000000000000", "amountOut": "4000000", "minAmountIn": "792000000000000000000000" }, "correlationId": "550e8400-e29b-41d4-a716-446655440003", "timestamp": "2026-10-08T12:00:00.000Z", "quoteRequest": { "dry": true, "swapType": "EXACT_OUTPUT", "originAsset": "nep141:wrap.near", "destinationAsset": "nep141:usdc.near", "amount": "4000000", "recipient": "0xescrow_example", "recipientType": "CONFIDENTIAL_INTENTS", "refundTo": "0xescrow_example", "refundType": "CONFIDENTIAL_INTENTS", "slippageTolerance": 100, "deadline": "2026-10-08T13:00:00.000Z", "appFees": [], "depositType": "CONFIDENTIAL_INTENTS", "connectedWallets": [ "0x1111111111111111111111111111111111111111" ], "sessionId": "hitch_550e8400-e29b-41d4-a716-446655440031", "confidentiality": "basic", "referral": "hitch", "depositMode": "SIMPLE" } }, "minAmountIn": "792000000000000000000000" }, "expectedFee": { "amount": "2000", "assetId": "nep141:usdc.near", "symbol": "USDC", "decimals": 6, "rounding": "down to the destination asset's smallest unit" }, "expiresAt": "2026-10-08T12:05:00.000Z", "nextStep": "For partner-managed execution, request a non-dry EXACT_OUTPUT 1Click quote for the combined target using your JWT, then generate and sign the operation-specific intent.", "swapType": "EXACT_OUTPUT" } }, "exactInputLive": { "summary": "Combined live quote for an exact input", "value": { "quoteId": "550e8400-e29b-41d4-a716-446655440018", "executionMode": "partner-managed", "feeBps": 10, "sourceAsset": { "assetId": "nep141:wrap.near", "symbol": "NEAR", "decimals": 24 }, "destinationAsset": { "assetId": "nep141:usdc.near", "symbol": "USDC", "decimals": 6 }, "leader": { "amountIn": "407706057266639649073549", "estimatedAmountOut": "4049800", "minAmountOut": "4009300" }, "followers": { "eligibleCount": 1, "excludedCount": 0, "amountIn": "808200000000000000000000", "estimatedGrossOutput": "2065800" }, "combined": { "amountIn": "1215906057266639649073549", "estimatedAmountOut": "6115600", "minAmountOut": "6054400", "quoteRequest": { "dry": false, "swapType": "EXACT_INPUT", "originAsset": "nep141:wrap.near", "destinationAsset": "nep141:usdc.near", "amount": "1215906057266639649073549", "recipient": "0xescrow_example", "recipientType": "CONFIDENTIAL_INTENTS", "refundTo": "0xescrow_example", "refundType": "CONFIDENTIAL_INTENTS", "slippageTolerance": 100, "deadline": "2026-10-08T13:00:00.000Z", "appFees": [], "depositType": "CONFIDENTIAL_INTENTS", "connectedWallets": [ "0x1111111111111111111111111111111111111111" ], "sessionId": "hitch_550e8400-e29b-41d4-a716-446655440031", "confidentiality": "basic", "referral": "hitch", "depositMode": "SIMPLE" }, "quoteResponse": { "signature": "example_provider_signature", "quote": { "amountIn": "1215906057266639649073549", "amountOut": "6115600", "minAmountOut": "6054400", "depositAddress": "0xdeposit_copy_exact_input", "deadline": "2026-10-08T13:00:00.000Z" }, "correlationId": "550e8400-e29b-41d4-a716-446655440000", "timestamp": "2026-10-08T12:00:00.000Z", "quoteRequest": { "dry": false, "swapType": "EXACT_INPUT", "originAsset": "nep141:wrap.near", "destinationAsset": "nep141:usdc.near", "amount": "1215906057266639649073549", "recipient": "0xescrow_example", "recipientType": "CONFIDENTIAL_INTENTS", "refundTo": "0xescrow_example", "refundType": "CONFIDENTIAL_INTENTS", "slippageTolerance": 100, "deadline": "2026-10-08T13:00:00.000Z", "appFees": [], "depositType": "CONFIDENTIAL_INTENTS", "connectedWallets": [ "0x1111111111111111111111111111111111111111" ], "sessionId": "hitch_550e8400-e29b-41d4-a716-446655440031", "confidentiality": "basic", "referral": "hitch", "depositMode": "SIMPLE" } } }, "expectedFee": { "amount": "2065", "assetId": "nep141:usdc.near", "symbol": "USDC", "decimals": 6, "rounding": "down to the destination asset's smallest unit" }, "expiresAt": "2026-10-08T13:00:00.000Z", "nextStep": "Review the live quote, then generate and sign the operation-specific intent before funding the deposit address.", "swapType": "EXACT_INPUT" } }, "exactOutputLive": { "summary": "Combined live quote for an exact output", "value": { "quoteId": "550e8400-e29b-41d4-a716-446655440009", "executionMode": "partner-managed", "feeBps": 10, "sourceAsset": { "assetId": "nep141:wrap.near", "symbol": "NEAR", "decimals": 24 }, "destinationAsset": { "assetId": "nep141:usdc.near", "symbol": "USDC", "decimals": 6 }, "leader": { "amountIn": "400000000000000000000000", "estimatedAmountOut": "2000000", "minAmountIn": "396000000000000000000000" }, "followers": { "eligibleCount": 1, "excludedCount": 0, "amountIn": "400000000000000000000000", "estimatedGrossOutput": "2000000" }, "combined": { "amountIn": "800000000000000000000000", "estimatedAmountOut": "4000000", "quoteRequest": { "dry": false, "swapType": "EXACT_OUTPUT", "originAsset": "nep141:wrap.near", "destinationAsset": "nep141:usdc.near", "amount": "4000000", "recipient": "0xescrow_example", "recipientType": "CONFIDENTIAL_INTENTS", "refundTo": "0xescrow_example", "refundType": "CONFIDENTIAL_INTENTS", "slippageTolerance": 100, "deadline": "2026-10-08T13:00:00.000Z", "appFees": [], "depositType": "CONFIDENTIAL_INTENTS", "connectedWallets": [ "0x1111111111111111111111111111111111111111" ], "sessionId": "hitch_550e8400-e29b-41d4-a716-446655440031", "confidentiality": "basic", "referral": "hitch", "depositMode": "SIMPLE" }, "quoteResponse": { "signature": "example_provider_signature", "quote": { "amountIn": "800000000000000000000000", "amountOut": "4000000", "minAmountIn": "792000000000000000000000", "depositAddress": "0xdeposit_copy_exact_output", "deadline": "2026-10-08T13:00:00.000Z" }, "correlationId": "550e8400-e29b-41d4-a716-446655440003", "timestamp": "2026-10-08T12:00:00.000Z", "quoteRequest": { "dry": false, "swapType": "EXACT_OUTPUT", "originAsset": "nep141:wrap.near", "destinationAsset": "nep141:usdc.near", "amount": "4000000", "recipient": "0xescrow_example", "recipientType": "CONFIDENTIAL_INTENTS", "refundTo": "0xescrow_example", "refundType": "CONFIDENTIAL_INTENTS", "slippageTolerance": 100, "deadline": "2026-10-08T13:00:00.000Z", "appFees": [], "depositType": "CONFIDENTIAL_INTENTS", "connectedWallets": [ "0x1111111111111111111111111111111111111111" ], "sessionId": "hitch_550e8400-e29b-41d4-a716-446655440031", "confidentiality": "basic", "referral": "hitch", "depositMode": "SIMPLE" } }, "minAmountIn": "792000000000000000000000" }, "expectedFee": { "amount": "2000", "assetId": "nep141:usdc.near", "symbol": "USDC", "decimals": 6, "rounding": "down to the destination asset's smallest unit" }, "expiresAt": "2026-10-08T13:00:00.000Z", "nextStep": "Review the live quote, then generate and sign the operation-specific intent before funding the deposit address.", "swapType": "EXACT_OUTPUT" } } } } } } } } }, "/copy-trades/submit": { "post": { "tags": [ "Copy trading" ], "operationId": "submitCopyTrade", "summary": "Submit a partner quote or signed Leader authorization", "description": "Hitch-managed: submit signedLeaderIntent. Partner-managed: first submit partnerQuote (the exact final non-dry 1Click request and signed response obtained with the partner’s JWT); Hitch returns a Leader contribution intent. Sign that payload and call again with signedLeaderIntent. Hitch uses its escrow key to send the pooled amount to 1Click. Partner JWTs and escrow keys are never sent in the request.", "x-hitch-status": "implemented locally", "security": [ { "PartnerApiKey": [], "UserSession": [] }, { "LeaderSessionCookie": [] } ], "requestBody": { "$ref": "#/components/requestBodies/CopyTradeSubmitRequest" }, "responses": { "202": { "description": "Accepted for processing. Continue with the returned next step or poll statusUrl.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CopyTradeSubmitResult" }, "examples": { "needsLeaderSignature": { "summary": "Partner quote accepted; Leader authorization is next", "value": { "tradeId": "550e8400-e29b-41d4-a716-446655440021", "status": "COLLECTING_CONTRIBUTIONS", "needsLeaderAuthorization": true, "leaderIntent": { "standard": "nep413", "payload": { "recipient": "intents.near", "nonce": "AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8=", "message": "{\"signer_id\":\"0x5870000000000000000000000000000019b5\",\"verifying_contract\":\"intents.near\",\"intents\":[{\"intent\":\"transfer\"}]}" }, "public_key": "ed25519:ExamplePublicKeyBase58", "signature": "ed25519:ExampleSignatureBase58" }, "message": "Sign this exact Leader contribution intent, then call this endpoint again with signedLeaderIntent." } }, "accepted": { "summary": "Signature accepted; poll the trade", "value": { "tradeId": "550e8400-e29b-41d4-a716-446655440021", "executionMode": "hitch-managed", "status": "COLLECTING_CONTRIBUTIONS", "statusUrl": "/v1/copy-trades/550e8400-e29b-41d4-a716-446655440021" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "428": { "$ref": "#/components/responses/PreconditionRequired" } } } }, "/copy-trades/{tradeId}": { "get": { "tags": [ "Copy trading" ], "operationId": "getCopyTrade", "summary": "Get a copied trade and its status", "description": "Returns only participant information visible to the current account. It omits other followers' confidential balances and signatures. Poll while status is non-terminal; the server reconciles provider state and account balance deltas before reporting settlement.", "x-hitch-status": "implemented locally", "security": [ { "PartnerApiKey": [], "UserSession": [] }, { "LeaderSessionCookie": [] }, { "FollowerSessionCookie": [] } ], "parameters": [ { "name": "tradeId", "in": "path", "required": true, "description": "Hitch trade ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Trade status and caller's own result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CopyTrade" }, "example": { "tradeId": "550e8400-e29b-41d4-a716-446655440021", "status": "SUCCESS", "providerStatus": "SUCCESS", "needsLeaderAuthorization": false, "leaderIntent": null, "actionRequired": null, "relayStatus": "CONFIRMED", "acceptedQuote": { "amountIn": "800000000000000000000000", "amountOut": "4000000", "minAmountOut": "3960000" }, "settledAmountOut": "4000000", "confirmedRefund": null, "updatedAt": "2026-10-08T12:10:00.000Z", "quoteId": "550e8400-e29b-41d4-a716-446655440022", "executionMode": "partner-managed", "swapType": "EXACT_OUTPUT", "requestedAmountOut": "4000000" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/deposit/notify": { "post": { "tags": [ "Deposits" ], "operationId": "submitDepositTransaction", "summary": "Notify Hitch about an external deposit transaction", "description": "Forwards the Hitch-generated quoteId and a source-chain transaction ID to the provider for earlier detection. It does not initiate the transfer; the user must send funds on the source chain separately.", "x-hitch-status": "implemented locally", "security": [ { "PartnerApiKey": [], "UserSession": [] }, { "LeaderSessionCookie": [] }, { "FollowerSessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "quoteId", "transactionId" ], "properties": { "quoteId": { "type": "string", "description": "Hitch-generated quote ID returned by POST /deposit/submit." }, "transactionId": { "type": "string", "description": "Source-network transaction hash or ID." } }, "additionalProperties": false }, "example": { "quoteId": "7bb70c67-872c-44a2-9a01-e762cbd15410", "transactionId": "0xabc123_example" } } } }, "responses": { "200": { "description": "Transaction notification accepted by 1Click.", "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string" } }, "additionalProperties": false }, "example": { "status": "KNOWN_DEPOSIT_TX" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/wallet-challenge": { "post": { "tags": [ "Wallet sessions" ], "operationId": "createWalletChallenge", "summary": "Create a wallet verification challenge", "description": "Creates a one-time challenge for an already-connected signer. EVM, Solana, and NEAR wallets sign the exact returned message. For passkeys, decode webauthnRequestOptions.challenge from base64url and call navigator.credentials.get(). Without includeBalances, it is SHA-256 of the exact UTF-8 message; in the combined first-party flow, it is SHA-256 of the returned balance-authorization payload. POST the resulting proof to /verify-wallet. The combined flow lets a client with a known passkey identity verify the wallet and authorize read-only balances with one assertion. For a discoverable passkey whose identity is not yet known, first discover the credential; balance authorization then needs a second assertion. Ordinary partner integrations should omit includeBalances.", "x-hitch-status": "implemented locally", "security": [ { "PartnerApiKey": [] }, {} ], "requestBody": { "$ref": "#/components/requestBodies/WalletChallengeRequest" }, "responses": { "201": { "description": "One-time challenge created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletChallenge" }, "examples": { "evm": { "summary": "EVM wallet challenge", "value": { "challengeId": "d56f3b4f-79b8-4c98-87ec-2014ba82c0a1", "walletType": "evm", "walletAddress": "0x1111111111111111111111111111111111111111", "intentsAccountId": "0x1111111111111111111111111111111111111111", "message": "Hitch wallet ownership verification\n\nOrigin: https://trade.example\nRole: FOLLOWER\nWallet: evm\nAddress: 0x1111111111111111111111111111111111111111\nIntents account: 0x1111111111111111111111111111111111111111\nNonce: AAECAwQFBgcICQoLDA0ODxAREhMUFRYX\nIssued at: 2026-10-09T12:00:00.000Z\nExpires at: 2026-10-09T12:05:00.000Z\nPurpose: Prove wallet control to Hitch. This does not authorize trading or delegation.", "expiresAt": "2026-10-09T12:05:00.000Z", "signatureStandard": "erc191", "standard": "erc191" } }, "solana": { "summary": "Solana wallet challenge", "value": { "challengeId": "d56f3b4f-79b8-4c98-87ec-2014ba82c0a2", "walletType": "solana", "walletAddress": "11111111111111111111111111111111", "intentsAccountId": "0000000000000000000000000000000000000000000000000000000000000000", "message": "Hitch wallet ownership verification\n\nOrigin: https://trade.example\nRole: FOLLOWER\nWallet: solana\nAddress: 11111111111111111111111111111111\nIntents account: 0000000000000000000000000000000000000000000000000000000000000000\nNonce: AAECAwQFBgcICQoLDA0ODxAREhMUFRYX\nIssued at: 2026-10-09T12:00:00.000Z\nExpires at: 2026-10-09T12:05:00.000Z\nPurpose: Prove wallet control to Hitch. This does not authorize trading or delegation.", "expiresAt": "2026-10-09T12:05:00.000Z", "signatureStandard": "raw_ed25519", "standard": "raw_ed25519" } }, "near": { "summary": "NEAR wallet challenge", "value": { "challengeId": "d56f3b4f-79b8-4c98-87ec-2014ba82c0a3", "walletType": "near", "walletAddress": "alice.near", "intentsAccountId": "alice.near", "message": "Hitch wallet ownership verification\n\nOrigin: https://trade.example\nRole: FOLLOWER\nWallet: near\nAddress: alice.near\nIntents account: alice.near\nNonce: AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8=\nIssued at: 2026-10-09T12:00:00.000Z\nExpires at: 2026-10-09T12:05:00.000Z\nPurpose: Prove wallet control to Hitch. This does not authorize trading or delegation.", "expiresAt": "2026-10-09T12:05:00.000Z", "signatureStandard": "nep413", "standard": "nep413", "nonce": "AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8=", "recipient": "trade.example" } }, "passkey": { "summary": "Already-connected passkey", "value": { "challengeId": "d56f3b4f-79b8-4c98-87ec-2014ba82c0a4", "walletType": "passkey", "walletAddress": "p256:39BmkNbgbHwBuDFnwjRRztHT8RqznwJwxTeCiY7AmGMjHmhPixoDgMqxz1f6fLjqgRJJtVTg3zS8kgh7UBCvv2LC", "intentsAccountId": "0xdbd37cede8c61ccfde77281670d79660519a0967", "message": "Hitch wallet ownership verification\n\nOrigin: https://trade.example\nRole: FOLLOWER\nWallet: passkey\nAddress: p256:39BmkNbgbHwBuDFnwjRRztHT8RqznwJwxTeCiY7AmGMjHmhPixoDgMqxz1f6fLjqgRJJtVTg3zS8kgh7UBCvv2LC\nIntents account: 0xdbd37cede8c61ccfde77281670d79660519a0967\nNonce: AAECAwQFBgcICQoLDA0ODxAREhMUFRYX\nIssued at: 2026-10-09T12:00:00.000Z\nExpires at: 2026-10-09T12:05:00.000Z\nPurpose: Prove wallet control to Hitch. This does not authorize trading or delegation.", "expiresAt": "2026-10-09T12:05:00.000Z", "signatureStandard": "webauthn", "standard": "webauthn", "webauthnRequestOptions": { "challenge": "jCbDZHYZv0SkqCGDfcP9wr86ZAOP2e24EdC63771QlM", "rpId": "trade.example", "timeout": 60000, "userVerification": "preferred" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/verify-wallet": { "post": { "tags": [ "Wallet sessions" ], "operationId": "verifyWallet", "summary": "Verify a connected wallet and create a session", "description": "Verifies the wallet-specific proof over the exact challenge returned by `POST /wallet-challenge`, resolves the Intents account from the connected signer identity, and creates a short-lived account-scoped session. For passkeys, the partner wallet supplies the connected public identity and returns the WebAuthn assertion fields in `signature`. This user session is not a 1Click JWT.", "x-hitch-status": "implemented locally", "requestBody": { "$ref": "#/components/requestBodies/WalletSessionRequest" }, "responses": { "201": { "description": "Wallet verified and session created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletSession" }, "examples": { "evm": { "summary": "Session from EVM wallet", "value": { "sessionToken": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "tokenType": "Bearer", "expiresAt": "2026-10-10T00:00:00.000Z", "account": { "accountId": "0x1111111111111111111111111111111111111111", "walletType": "evm", "walletAddress": "0x1111111111111111111111111111111111111111", "role": "follower", "verifiedAt": "2026-10-09T12:00:00.000Z" }, "verified": true, "role": "FOLLOWER", "walletType": "evm", "walletAddress": "0x1111111111111111111111111111111111111111", "intentsAccountId": "0x1111111111111111111111111111111111111111", "sessionId": "550e8400-e29b-41d4-a716-446655440041" } }, "solana": { "summary": "Session from Solana wallet", "value": { "sessionToken": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "tokenType": "Bearer", "expiresAt": "2026-10-10T00:00:00.000Z", "account": { "accountId": "0000000000000000000000000000000000000000000000000000000000000000", "walletType": "solana", "walletAddress": "11111111111111111111111111111111", "role": "follower", "verifiedAt": "2026-10-09T12:00:00.000Z" }, "verified": true, "role": "FOLLOWER", "walletType": "solana", "walletAddress": "11111111111111111111111111111111", "intentsAccountId": "0000000000000000000000000000000000000000000000000000000000000000", "sessionId": "550e8400-e29b-41d4-a716-446655440042" } }, "near": { "summary": "Session from NEAR wallet", "value": { "sessionToken": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "tokenType": "Bearer", "expiresAt": "2026-10-10T00:00:00.000Z", "account": { "accountId": "alice.near", "walletType": "near", "walletAddress": "alice.near", "role": "follower", "verifiedAt": "2026-10-09T12:00:00.000Z" }, "verified": true, "role": "FOLLOWER", "walletType": "near", "walletAddress": "alice.near", "intentsAccountId": "alice.near", "sessionId": "550e8400-e29b-41d4-a716-446655440043" } }, "passkey": { "summary": "Session from passkey", "value": { "sessionToken": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "tokenType": "Bearer", "expiresAt": "2026-10-10T00:00:00.000Z", "account": { "accountId": "0xdbd37cede8c61ccfde77281670d79660519a0967", "walletType": "passkey", "walletAddress": "p256:39BmkNbgbHwBuDFnwjRRztHT8RqznwJwxTeCiY7AmGMjHmhPixoDgMqxz1f6fLjqgRJJtVTg3zS8kgh7UBCvv2LC", "role": "follower", "verifiedAt": "2026-10-09T12:00:00.000Z" }, "verified": true, "role": "FOLLOWER", "walletType": "passkey", "walletAddress": "p256:39BmkNbgbHwBuDFnwjRRztHT8RqznwJwxTeCiY7AmGMjHmhPixoDgMqxz1f6fLjqgRJJtVTg3zS8kgh7UBCvv2LC", "intentsAccountId": "0xdbd37cede8c61ccfde77281670d79660519a0967", "sessionId": "550e8400-e29b-41d4-a716-446655440044" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "PartnerApiKey": [] }, {} ] } }, "/leaders/register": { "post": { "tags": [ "Leaders" ], "operationId": "registerLeader", "summary": "Register the current account as a leader", "description": "Registers the verified account with a fee in basis points. A fee change affects future trades only. When existing followers must reconfirm, copy trading is disabled for each follower until that follower confirms the new fee.", "x-hitch-status": "implemented locally", "security": [ { "PartnerApiKey": [], "UserSession": [] }, { "LeaderSessionCookie": [] } ], "requestBody": { "$ref": "#/components/requestBodies/LeaderRegistrationRequest" }, "responses": { "201": { "description": "Leader registered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaderWriteResult" }, "example": { "registered": true, "leaderAccountId": "0x5870000000000000000000000000000019b5", "feeBps": 10, "feeChangePending": false, "registeredAt": "2026-10-09T12:05:00.000Z", "leader": { "accountId": "0x5870000000000000000000000000000019b5", "createdAt": "2026-10-09T12:05:00.000Z", "blockchain": "base", "copyTradingFeeBps": 10, "copyTradingFeeVersion": 1 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/leaders/change-fee": { "patch": { "tags": [ "Leaders" ], "operationId": "updateLeaderFee", "summary": "Change the current leader's fee", "description": "Updates the current Leader fee through the same registration service. The returned representation is the current Leader record; existing followers who have not confirmed the new fee are excluded from future copy-trade quotes.", "x-hitch-status": "implemented locally", "security": [ { "PartnerApiKey": [], "UserSession": [] }, { "LeaderSessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "feeBps" ], "properties": { "feeBps": { "type": "integer", "minimum": 0, "maximum": 25, "description": "Leader fee in basis points; 1 bps = 0.01%." } }, "additionalProperties": false }, "example": { "feeBps": 10 } } } }, "responses": { "200": { "description": "Fee updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaderWriteResult" }, "example": { "registered": true, "leaderAccountId": "0x5870000000000000000000000000000019b5", "feeBps": 10, "feeChangePending": false, "registeredAt": "2026-10-09T12:05:00.000Z", "leader": { "accountId": "0x5870000000000000000000000000000019b5", "createdAt": "2026-10-09T12:05:00.000Z", "blockchain": "base", "copyTradingFeeBps": 10, "copyTradingFeeVersion": 2 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/followers": { "get": { "tags": [ "Leaders" ], "operationId": "getFollowers", "summary": "List the authenticated leader’s followers", "description": "Returns followers for the leader account identified by the verified user session. No leader account ID is needed because this endpoint only exposes the authenticated leader’s own list. Does not reveal follower balances. An unconfirmed follower is inactive for copy-trade sizing.", "x-hitch-status": "implemented locally", "security": [ { "PartnerApiKey": [], "UserSession": [] }, { "LeaderSessionCookie": [] } ], "responses": { "200": { "description": "Follower page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FollowerList" }, "example": { "leaderAccountId": "0x5870000000000000000000000000000019b5", "followers": [ { "accountId": "solana:11111111111111111111111111111111", "copiedTradeCount": 3, "walletType": "solana", "feeConfirmed": true } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/follows/fee-confirmation": { "post": { "tags": [ "Follows" ], "operationId": "confirmLeaderFee", "summary": "Confirm the leader's current fee", "description": "Records the current follower's explicit consent to the leader's latest fee. This endpoint takes no request body; omit Content-Type. This confirmation is separate from follow authorization. Copy trading for this follower becomes eligible only after required key delegation and fee confirmation are both active.", "x-hitch-status": "implemented locally", "security": [ { "PartnerApiKey": [], "UserSession": [] }, { "FollowerSessionCookie": [] } ], "parameters": [ { "name": "leaderId", "in": "query", "required": false, "description": "Optional Leader account ID to select the active follow.", "schema": { "type": "string" } }, { "name": "followId", "in": "query", "required": false, "description": "Optional active follow relationship ID to select. Omit both selectors when the Follower has one active Leader.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Fee consent recorded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FollowFeeConfirmationResult" }, "example": { "confirmed": true, "leaderAccountId": "0x5870000000000000000000000000000019b5", "copyTradingFeeBps": 10 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/account/balance-challenge": { "post": { "tags": [ "Accounts" ], "operationId": "createBalanceChallenge", "summary": "Create a read-only balance authorization challenge", "description": "Returns an operation-specific payload for the verified wallet to sign before Hitch can read its Intents balances. This signature authorizes balance access only.", "x-hitch-status": "implemented locally", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Wallet-specific balance signing payload.", "content": { "application/json": { "schema": { "type": "object", "required": [ "standard", "payload", "requestId" ], "properties": { "standard": { "type": "string", "enum": [ "erc191", "raw_ed25519", "nep413", "webauthn" ] }, "payload": { "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/IntentsNep413Payload" } ] }, "requestId": { "type": "string" } }, "additionalProperties": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/account/balance-authorization": { "post": { "tags": [ "Accounts" ], "operationId": "authorizeBalances", "summary": "Authorize read-only balance access", "description": "Verifies the signed balance authorization and requests the short-lived balance access token from 1Click. This does not authorize a trade.", "x-hitch-status": "implemented locally", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "signedData" ], "properties": { "signedData": { "$ref": "#/components/schemas/SignedIntent" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Balance authorization result.", "content": { "application/json": { "schema": { "type": "object", "required": [ "authorized" ], "properties": { "authorized": { "type": "boolean" } }, "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/copy-trades/prepare": { "post": { "tags": [ "Copy trading" ], "operationId": "prepareCopyTrade", "summary": "Prepare a copied trade", "description": "Consumes a Hitch dry quote, refreshes participant balances, persists the participant plan, and creates the trade escrow. In partner-managed mode, the response includes the final non-dry 1Click quote request addressed to that escrow. The partner should get the live quote with its own JWT before submitting it.", "x-hitch-status": "implemented locally", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "quoteId", "executionMode", "idempotencyKey" ], "properties": { "quoteId": { "type": "string", "description": "Hitch quote reference returned by POST /copy-trades/get-quote." }, "executionMode": { "$ref": "#/components/schemas/ExecutionMode" }, "idempotencyKey": { "type": "string", "minLength": 8, "maxLength": 120 } }, "additionalProperties": false }, "example": { "quoteId": "550e8400-e29b-41d4-a716-446655440010", "executionMode": "partner-managed", "idempotencyKey": "copy_trade_user123_001" } } } }, "responses": { "201": { "description": "Prepared trade and next action.", "content": { "application/json": { "schema": { "type": "object", "required": [ "quoteId", "tradeId", "executionMode", "status", "aggregateAmountIn", "expiresAt" ], "properties": { "quoteId": { "type": "string" }, "tradeId": { "type": "string" }, "executionMode": { "$ref": "#/components/schemas/ExecutionMode" }, "status": { "type": "string" }, "aggregateAmountIn": { "type": "string" }, "escrowAccountId": { "type": "string" }, "quoteRequest": { "$ref": "#/components/schemas/OneClickQuoteRequest" }, "leaderIntent": { "$ref": "#/components/schemas/SignedIntent" }, "expiresAt": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "example": { "quoteId": "550e8400-e29b-41d4-a716-446655440011", "tradeId": "550e8400-e29b-41d4-a716-446655440021", "executionMode": "partner-managed", "status": "AWAITING_LEADER_AUTHORIZATION", "aggregateAmountIn": "1215906057266639649073549", "escrowAccountId": "0xescrow_example", "quoteRequest": { "dry": false, "swapType": "EXACT_INPUT", "originAsset": "nep141:wrap.near", "destinationAsset": "nep141:usdc.near", "amount": "1215906057266639649073549", "recipient": "0xescrow_example", "refundTo": "0xescrow_example" }, "leaderIntent": { "standard": "nep413", "payload": { "recipient": "intents.near", "nonce": "AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8=", "message": "{\"signer_id\":\"0x5870000000000000000000000000000019b5\",\"intents\":[{\"intent\":\"transfer\"}]}" }, "public_key": "ed25519:ExamplePublicKeyBase58", "signature": "ed25519:ExampleSignatureBase58" }, "expiresAt": "2026-10-09T13:00:00.000Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "428": { "$ref": "#/components/responses/PreconditionRequired" } } } }, "/copy-trades/{tradeId}/cancel": { "post": { "tags": [ "Copy trading" ], "operationId": "cancelCopyTrade", "summary": "Cancel an unsubmitted copied trade", "description": "Cancels a prepared trade when its Leader contribution has not been irreversibly submitted. If a contribution is already in flight, the response may indicate that the trade is being reconciled or refunded.", "x-hitch-status": "implemented locally", "parameters": [ { "name": "tradeId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Trade cancellation state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CopyTradeCancelResult" }, "examples": { "cancelled": { "value": { "tradeId": "550e8400-e29b-41d4-a716-446655440021", "status": "CANCELLED" } }, "waitingForContributions": { "value": { "tradeId": "550e8400-e29b-41d4-a716-446655440021", "status": "CANCEL_REQUESTED", "actionRequired": "WAIT_FOR_CANCELLATION_STATUS" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" } }, "security": [ { "PartnerApiKey": [], "UserSession": [] }, { "LeaderSessionCookie": [] } ] } }, "/follows/current": { "get": { "tags": [ "Follows" ], "operationId": "getCurrentFollow", "summary": "Get current follow relationship and pending operation", "description": "Returns the authenticated Follower account’s current Leader, fee-consent state, and pending follow operation.", "x-hitch-status": "implemented locally", "responses": { "200": { "description": "Current follow state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FollowCurrent" }, "example": { "activeLeaderAccountId": "0x5870000000000000000000000000000019b5", "activeLeaderFeeConfirmed": true, "pendingOperation": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/follows/cancel": { "post": { "tags": [ "Follows" ], "operationId": "cancelFollowOperation", "summary": "Cancel a pending follow operation", "description": "Cancels or reconciles the pending follow operation identified by operationId. This endpoint takes no request body; omit Content-Type.", "x-hitch-status": "implemented locally", "parameters": [ { "name": "operationId", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Cancellation result.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/follows/{operationId}": { "get": { "tags": [ "Follows" ], "operationId": "getFollowOperationStatus", "summary": "Get follow operation status", "description": "Gets the current status of the pending follow/unfollow operation identified by operationId.", "x-hitch-status": "implemented locally", "parameters": [ { "name": "operationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Follow operation status.", "content": { "application/json": { "schema": { "type": "object", "required": [ "operationId", "status" ], "properties": { "operationId": { "type": "string" }, "status": { "type": "string" }, "needsSignature": { "type": "boolean" }, "payload": { "type": [ "string", "null" ] }, "serverPublicKey": { "type": "string" }, "activeLeaderAccountId": { "type": [ "string", "null" ] }, "relayStatus": { "type": "string" }, "transactionHash": { "type": "string" }, "errorCode": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "example": { "operationId": "5bffb63b-8530-46a3-99f8-bf29b591bb2c", "status": "AWAITING_SIGNATURE", "needsSignature": true, "payload": "{\"signer_id\":\"alice.near\",\"verifying_contract\":\"intents.near\",\"deadline\":\"2026-10-09T13:00:00.000Z\",\"nonce\":\"AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8=\",\"intents\":[{\"intent\":\"add_public_key\",\"public_key\":\"ed25519:ExampleServerPublicKeyBase58\"}]}", "serverPublicKey": "ed25519:ExampleServerPublicKeyBase58", "errorCode": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/follows/prepare-operation": { "post": { "tags": [ "Follows" ], "operationId": "prepareFollowOperation", "summary": "Prepare a follow or unfollow operation", "description": "Creates a pending operation and returns the exact wallet-signing payload to add or remove the configured Hitch public key from the selected Leader relationship. Set operationType to follow or unfollow and always provide the selected leaderId. Following explicitly delegates copy-trade transfer authority to Hitch while the relationship is active. No delegation is added or removed until the signed operation is submitted to POST /follows/confirm-action and reconciled.", "x-hitch-status": "implemented locally", "security": [ { "PartnerApiKey": [], "UserSession": [] }, { "FollowerSessionCookie": [] } ], "responses": { "201": { "description": "Pending follow operation and wallet payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FollowOperationPreparation" }, "examples": { "follow": { "summary": "Prepared follow operation", "value": { "operationId": "5bffb63b-8530-46a3-99f8-bf29b591bb2c", "action": "FOLLOW", "leaderAccountId": "0x5870000000000000000000000000000019b5", "serverPublicKey": "ed25519:ExampleServerPublicKeyBase58", "payload": "{\"signer_id\":\"alice.near\",\"verifying_contract\":\"intents.near\",\"deadline\":\"2026-10-09T13:00:00.000Z\",\"nonce\":\"AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8=\",\"intents\":[{\"intent\":\"add_public_key\",\"public_key\":\"ed25519:ExampleServerPublicKeyBase58\"}]}", "copyTradingFeeBps": 10, "status": "AWAITING_SIGNATURE" } }, "unfollow": { "summary": "Prepared unfollow operation", "value": { "operationId": "0c6f4b3e-a2e2-4b9f-b937-60a9d73658d2", "action": "UNFOLLOW", "leaderAccountId": "0x5870000000000000000000000000000019b5", "serverPublicKey": "ed25519:ExampleServerPublicKeyBase58", "payload": "{\"signer_id\":\"alice.near\",\"verifying_contract\":\"intents.near\",\"deadline\":\"2026-10-09T13:00:00.000Z\",\"nonce\":\"AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8=\",\"intents\":[{\"intent\":\"remove_public_key\",\"public_key\":\"ed25519:ExampleServerPublicKeyBase58\"}]}", "copyTradingFeeBps": null, "status": "AWAITING_SIGNATURE" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "operationType", "leaderId" ], "properties": { "operationType": { "type": "string", "enum": [ "follow", "unfollow" ], "description": "Whether to prepare a new follow or remove the active follow delegation." }, "leaderId": { "type": "string", "description": "Intents account ID of the specific registered Leader to follow or unfollow.", "pattern": "^0x[0-9a-fA-F]{40}$" } }, "additionalProperties": false }, "examples": { "follow": { "summary": "Prepare a follow", "value": { "operationType": "follow", "leaderId": "0x5870000000000000000000000000000019b5" } }, "unfollow": { "summary": "Prepare an unfollow", "value": { "operationType": "unfollow", "leaderId": "0x5870000000000000000000000000000019b5" } } } } } } } }, "/follows/confirm-action": { "post": { "tags": [ "Follows" ], "operationId": "confirmFollowAction", "summary": "Submit the signed follow or unfollow action", "description": "Submit the wallet signature over the exact payload returned by prepare-operation. The query parameter is the operationId returned by that call. Wallet-specific examples below demonstrate the signature envelope for a follow; for an unfollow, sign the returned payload containing remove_public_key unchanged. A successful response may still be processing; poll GET /follows/{operationId}.", "x-hitch-status": "implemented locally", "security": [ { "PartnerApiKey": [], "UserSession": [] }, { "FollowerSessionCookie": [] } ], "parameters": [ { "name": "operationId", "in": "query", "required": true, "description": "Pending follow or unfollow operation ID returned by prepare-operation.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "signedData" ], "properties": { "signedData": { "$ref": "#/components/schemas/SignedIntent", "description": "Exact wallet signature envelope for the operation payload." } }, "additionalProperties": false }, "examples": { "evm": { "summary": "EVM wallet (ERC-191)", "description": "Use the exact payload string returned by prepare-operation. WalletConnect on an EVM chain uses this same format.", "value": { "signedData": { "standard": "erc191", "payload": "{\"signer_id\":\"0x1111111111111111111111111111111111111111\",\"verifying_contract\":\"intents.near\",\"deadline\":\"2026-10-09T13:00:00.000Z\",\"nonce\":\"AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8=\",\"intents\":[{\"intent\":\"add_public_key\",\"public_key\":\"ed25519:ExampleServerPublicKeyBase58\"}]}", "signature": "secp256k1:ExampleSignatureBase58" } } }, "solana": { "summary": "Solana wallet (raw Ed25519)", "description": "The Intents signer_id is the lowercase hex encoding of the Solana public key. WalletConnect on Solana uses this same format.", "value": { "signedData": { "standard": "raw_ed25519", "payload": "{\"signer_id\":\"0000000000000000000000000000000000000000000000000000000000000000\",\"verifying_contract\":\"intents.near\",\"deadline\":\"2026-10-09T13:00:00.000Z\",\"nonce\":\"AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8=\",\"intents\":[{\"intent\":\"add_public_key\",\"public_key\":\"ed25519:ExampleServerPublicKeyBase58\"}]}", "public_key": "ed25519:11111111111111111111111111111111", "signature": "ed25519:ExampleSignatureBase58" } } }, "near": { "summary": "NEAR wallet (NEP-413)", "description": "NEP-413 signs the message inside the envelope. Keep the returned recipient, nonce, and message unchanged.", "value": { "signedData": { "standard": "nep413", "payload": { "recipient": "intents.near", "nonce": "AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8=", "message": "{\"deadline\":\"2026-10-09T13:00:00.000Z\",\"intents\":[{\"intent\":\"add_public_key\",\"public_key\":\"ed25519:ExampleServerPublicKeyBase58\"}],\"signer_id\":\"alice.near\"}" }, "public_key": "ed25519:ExamplePublicKeyBase58", "signature": "ed25519:ExampleSignatureBase58" } } }, "passkey": { "summary": "Passkey (WebAuthn assertion)", "description": "Use SHA-256 of the exact UTF-8 payload string as the WebAuthn challenge, then return the assertion fields and connected passkey public key.", "value": { "signedData": { "standard": "webauthn", "payload": "{\"signer_id\":\"0xdbd37cede8c61ccfde77281670d79660519a0967\",\"verifying_contract\":\"intents.near\",\"deadline\":\"2026-10-09T13:00:00.000Z\",\"nonce\":\"AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8=\",\"intents\":[{\"intent\":\"add_public_key\",\"public_key\":\"ed25519:ExampleServerPublicKeyBase58\"}]}", "public_key": "p256:39BmkNbgbHwBuDFnwjRRztHT8RqznwJwxTeCiY7AmGMjHmhPixoDgMqxz1f6fLjqgRJJtVTg3zS8kgh7UBCvv2LC", "signature": "p256:ExampleCompactSignatureBase58", "client_data_json": "base64url_client_data_json_from_assertion", "authenticator_data": "base64url_authenticator_data_from_assertion" } } } } } } }, "responses": { "202": { "description": "Signature accepted; operation is still being reconciled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationStatus" }, "example": { "operationId": "5bffb63b-8530-46a3-99f8-bf29b591bb2c", "status": "PROCESSING", "updatedAt": "2026-10-09T12:06:00.000Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/account/logout": { "post": { "tags": [ "Accounts" ], "operationId": "logoutWalletSession", "summary": "End the current browser wallet session", "description": "Revokes the session selected by X-Hitch-Role and clears its HttpOnly cookie.", "x-hitch-status": "implemented locally", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Session logout result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "loggedOut": { "type": "boolean" } }, "additionalProperties": true } } } } } } } }, "components": { "securitySchemes": { "PartnerApiKey": { "type": "apiKey", "in": "header", "name": "X-Partner-Api-Key", "description": "Secret partner-server credential issued through the Hitch admin panel. Store in a managed server secret store. Never embed it in browser/mobile code." }, "UserSession": { "type": "http", "scheme": "bearer", "bearerFormat": "htu_…", "description": "Short-lived Hitch user session returned after wallet verification when using a partner API key. It is scoped to one verified Intents account and role." }, "LeaderSessionCookie": { "type": "apiKey", "in": "cookie", "name": "hitch_session_leader", "description": "First-party browser session cookie for Leader operations. Browser clients also send X-Hitch-Role: LEADER." }, "FollowerSessionCookie": { "type": "apiKey", "in": "cookie", "name": "hitch_session_follower", "description": "First-party browser session cookie for Follower operations. Browser clients also send X-Hitch-Role: FOLLOWER." } }, "parameters": { "QuoteId": { "name": "quoteId", "in": "query", "required": true, "description": "Hitch-generated deposit quote ID returned by POST /deposit/submit in Hitch-managed mode. It is not the 1Click correlationId. Pass it to GET /deposit/get or in the body of POST /deposit/notify.", "schema": { "type": "string" } } }, "requestBodies": { "WalletChallengeRequest": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "walletType", "walletAddress", "role", "origin" ], "properties": { "walletType": { "$ref": "#/components/schemas/WalletType" }, "walletAddress": { "type": "string", "description": "Public identity of the already-connected signer; for passkeys this is the signer public-key identifier supplied by the partner wallet." }, "role": { "$ref": "#/components/schemas/WalletRoleInput" }, "origin": { "type": "string", "format": "uri", "description": "Partner application's trusted HTTPS origin; challenge is bound to this origin." }, "credentialId": { "type": "string", "description": "Optional credential ID supplied by the connected passkey wallet to select its assertion credential." }, "includeBalances": { "type": "boolean", "description": "First-party combined wallet and balance authorization path. If the passkey public identity is already known, one assertion can verify the wallet and authorize balance reads. An undiscovered passkey requires a discovery assertion before this account-specific challenge. Omit for standard partner wallet verification." } }, "additionalProperties": false }, "example": { "walletType": "passkey", "walletAddress": "p256:39BmkNbgbHwBuDFnwjRRztHT8RqznwJwxTeCiY7AmGMjHmhPixoDgMqxz1f6fLjqgRJJtVTg3zS8kgh7UBCvv2LC", "role": "follower", "origin": "https://trade.example" }, "examples": { "evm": { "summary": "EVM wallet (for example, MetaMask)", "value": { "walletType": "evm", "walletAddress": "0x1111111111111111111111111111111111111111", "role": "follower", "origin": "https://trade.example" } }, "solana": { "summary": "Solana wallet (for example, Phantom)", "value": { "walletType": "solana", "walletAddress": "11111111111111111111111111111111", "role": "follower", "origin": "https://trade.example" } }, "walletConnectEvm": { "summary": "WalletConnect connected to an EVM chain", "description": "Same signer family and challenge flow as an injected EVM wallet.", "value": { "walletType": "evm", "walletAddress": "0x2222222222222222222222222222222222222222", "role": "follower", "origin": "https://trade.example" } }, "walletConnectSolana": { "summary": "WalletConnect connected to Solana", "description": "Same signer family and challenge flow as a Solana wallet.", "value": { "walletType": "solana", "walletAddress": "22222222222222222222222222222222", "role": "follower", "origin": "https://trade.example" } }, "near": { "summary": "NEAR wallet (for example, Meteor Wallet)", "value": { "walletType": "near", "walletAddress": "alice.near", "role": "follower", "origin": "https://trade.example" } }, "passkey": { "summary": "Already-connected passkey", "value": { "walletType": "passkey", "walletAddress": "p256:39BmkNbgbHwBuDFnwjRRztHT8RqznwJwxTeCiY7AmGMjHmhPixoDgMqxz1f6fLjqgRJJtVTg3zS8kgh7UBCvv2LC", "credentialId": "base64url_raw_credential_id", "role": "follower", "origin": "https://trade.example" } } } } } }, "WalletSessionRequest": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "challengeId", "signature" ], "properties": { "challengeId": { "type": "string", "description": "One-time ID returned by the challenge call." }, "signature": { "$ref": "#/components/schemas/WalletProof", "description": "Wallet-specific proof over the exact challenge. Passkey flows include credential ID, clientDataJSON, authenticatorData, and signature bytes." } }, "additionalProperties": false }, "example": { "challengeId": "f6cd8772-7604-4f7d-a066-e08c07abe619", "signature": { "signature": "0xExampleEvmSignature" } }, "examples": { "evm": { "summary": "EVM or WalletConnect EVM", "value": { "challengeId": "d56f3b4f-79b8-4c98-87ec-2014ba82c0a1", "signature": { "signature": "0xExampleEvmSignature" } } }, "solana": { "summary": "Solana or WalletConnect Solana", "value": { "challengeId": "d56f3b4f-79b8-4c98-87ec-2014ba82c0a2", "signature": { "signature": "base64_encoded_64_byte_ed25519_signature" } } }, "near": { "summary": "NEAR NEP-413", "value": { "challengeId": "d56f3b4f-79b8-4c98-87ec-2014ba82c0a3", "signature": { "accountId": "alice.near", "publicKey": "ed25519:ExamplePublicKeyBase58", "signature": "ed25519:ExampleSignatureBase58" } } }, "passkey": { "summary": "Passkey WebAuthn assertion", "value": { "challengeId": "d56f3b4f-79b8-4c98-87ec-2014ba82c0a4", "signature": { "publicKey": "p256:39BmkNbgbHwBuDFnwjRRztHT8RqznwJwxTeCiY7AmGMjHmhPixoDgMqxz1f6fLjqgRJJtVTg3zS8kgh7UBCvv2LC", "payload": "Hitch wallet ownership verification\n\nOrigin: https://trade.example\nRole: FOLLOWER\nWallet: passkey\nAddress: p256:39BmkNbgbHwBuDFnwjRRztHT8RqznwJwxTeCiY7AmGMjHmhPixoDgMqxz1f6fLjqgRJJtVTg3zS8kgh7UBCvv2LC\nIntents account: 0xdbd37cede8c61ccfde77281670d79660519a0967\nNonce: AAECAwQFBgcICQoLDA0ODxAREhMUFRYX\nIssued at: 2026-10-09T12:00:00.000Z\nExpires at: 2026-10-09T12:05:00.000Z\nPurpose: Prove wallet control to Hitch. This does not authorize trading or delegation.", "clientDataJSON": "eyJ0eXBlIjoid2ViYXV0aG4uZ2V0IiwiY2hhbGxlbmdlIjoiakNiRFpIWVp2MFNrcUNHRGZjUDl3cjg2WkFPUDJlMjRFZEM2Mzc3MVFsTSIsIm9yaWdpbiI6Imh0dHBzOi8vdHJhZGUuZXhhbXBsZSIsImNyb3NzT3JpZ2luIjpmYWxzZX0", "authenticatorData": "kcpKvmBnqTEDzpOYZED-Qm4oyHkFky8k_f9Z8f4jMgMBAAAAAA", "signature": "p256:99eUso3aSbE9tqGSTXzo3TLfKb9RkMTURrHKQ1K7Zh3BbeqPevr5E1iCbpTjqHuTFLtfxTTD5ekfVuZFzQyEQf8" } } } } } } }, "DepositQuoteRequest": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "assetId", "network", "executionMode" ], "properties": { "assetId": { "type": "string", "description": "Canonical Intents destination asset ID." }, "network": { "type": "string", "description": "Source network identifier supported by the selected asset." }, "amount": { "type": "string", "pattern": "^[0-9]+$", "description": "Optional only for the local first-party Hitch-managed flexible-deposit form. Partner-managed integrations must provide a positive source-token amount in base units." }, "executionMode": { "$ref": "#/components/schemas/ExecutionMode" }, "deadline": { "type": "string", "format": "date-time", "description": "Optional requested expiry; Hitch validates and may shorten it to provider limits." } }, "additionalProperties": false }, "example": { "assetId": "nep141:usdc.near", "network": "eth", "amount": "1000000", "executionMode": "partner-managed" } } } }, "LeaderRegistrationRequest": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "feeBps": { "type": "integer", "minimum": 0, "maximum": 25, "description": "Copy-trading fee in basis points, capped at 25." }, "blockchain": { "type": "string", "description": "EVM network label for EVM signers (for example, base or ethereum). Other wallet families use their wallet type as the network." } }, "additionalProperties": false }, "example": { "feeBps": 10, "blockchain": "base" } } } }, "SingleQuoteRequest": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "sourceAssetId", "destinationAssetId", "dry", "swapType", "slippageToleranceBps", "executionMode" ], "properties": { "sourceAssetId": { "type": "string", "description": "Canonical Intents source asset ID." }, "destinationAssetId": { "type": "string", "description": "Canonical Intents destination asset ID." }, "amountIn": { "type": "string", "pattern": "^[0-9]+$", "description": "Required for EXACT_INPUT: source amount in source-token base units." }, "slippageToleranceBps": { "type": "integer", "minimum": 0, "maximum": 5000, "description": "Maximum allowed price movement in basis points; 100 bps = 1%." }, "appFees": { "type": "array", "items": { "$ref": "#/components/schemas/AppFee" }, "description": "Optional application fee entries forwarded to 1Click, subject to provider limits." }, "executionMode": { "$ref": "#/components/schemas/ExecutionMode" }, "dry": { "type": "boolean", "description": "Set true for a preview without deposit instructions; set false for a live quote that can include deposit instructions." }, "swapType": { "type": "string", "enum": [ "EXACT_INPUT", "EXACT_OUTPUT" ], "description": "EXACT_INPUT fixes the source amount; EXACT_OUTPUT fixes the desired destination amount." }, "amountOut": { "type": "string", "pattern": "^[0-9]+$", "description": "Required for EXACT_OUTPUT: desired amount in destination-token base units." } }, "additionalProperties": false, "oneOf": [ { "properties": { "swapType": { "const": "EXACT_INPUT" } }, "required": [ "swapType", "amountIn" ], "not": { "required": [ "amountOut" ] } }, { "properties": { "swapType": { "const": "EXACT_OUTPUT" } }, "required": [ "swapType", "amountOut" ], "not": { "required": [ "amountIn" ] } } ] }, "examples": { "exactInputDry": { "summary": "Dry quote for an exact input", "value": { "sourceAssetId": "nep141:usdc.near", "destinationAssetId": "nep141:wrap.near", "dry": true, "swapType": "EXACT_INPUT", "amountIn": "1000000", "slippageToleranceBps": 100, "appFees": [], "executionMode": "hitch-managed" } }, "exactOutputDry": { "summary": "Dry quote for an exact output", "value": { "sourceAssetId": "nep141:usdc.near", "destinationAssetId": "nep141:wrap.near", "dry": true, "swapType": "EXACT_OUTPUT", "amountOut": "1000000000000000000000000", "slippageToleranceBps": 100, "appFees": [], "executionMode": "hitch-managed" } }, "exactInputLive": { "summary": "Live quote for an exact input", "value": { "sourceAssetId": "nep141:usdc.near", "destinationAssetId": "nep141:wrap.near", "dry": false, "swapType": "EXACT_INPUT", "amountIn": "1000000", "slippageToleranceBps": 100, "appFees": [], "executionMode": "hitch-managed" } }, "exactOutputLive": { "summary": "Live quote for an exact output", "value": { "sourceAssetId": "nep141:usdc.near", "destinationAssetId": "nep141:wrap.near", "dry": false, "swapType": "EXACT_OUTPUT", "amountOut": "1000000000000000000000000", "slippageToleranceBps": 100, "appFees": [], "executionMode": "hitch-managed" } } } } } }, "CopyTradeQuoteRequest": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "sourceAssetId", "destinationAssetId", "dry", "swapType", "slippageToleranceBps", "executionMode" ], "properties": { "sourceAssetId": { "type": "string", "description": "Canonical Intents source asset used for the leader and all follower contributions." }, "destinationAssetId": { "type": "string", "description": "Canonical Intents destination asset." }, "leaderAmountIn": { "type": "string", "pattern": "^[0-9]+$", "description": "Required for EXACT_INPUT: leader exact input in source-token base units." }, "slippageToleranceBps": { "type": "integer", "minimum": 0, "maximum": 5000, "description": "Maximum slippage forwarded to 1Click." }, "appFees": { "type": "array", "items": { "$ref": "#/components/schemas/AppFee" }, "description": "Application fees to include in the 1Click quote request. The partner's quote may differ." }, "executionMode": { "$ref": "#/components/schemas/ExecutionMode" }, "dry": { "type": "boolean", "description": "Must be true. The final live 1Click quote is created only after the escrow exists." }, "swapType": { "type": "string", "enum": [ "EXACT_INPUT", "EXACT_OUTPUT" ], "description": "EXACT_INPUT takes the leader source amount; EXACT_OUTPUT targets a combined destination amount shared across the pooled trade." }, "combinedAmountOut": { "type": "string", "pattern": "^[0-9]+$", "description": "Required for EXACT_OUTPUT: fixed gross output target for the entire pooled trade in destination-token base units. Hitch later distributes the settled output pro rata by each participant’s confirmed source contribution." } }, "additionalProperties": false, "oneOf": [ { "properties": { "swapType": { "const": "EXACT_INPUT" } }, "required": [ "swapType", "leaderAmountIn" ], "not": { "required": [ "combinedAmountOut" ] } }, { "properties": { "swapType": { "const": "EXACT_OUTPUT" } }, "required": [ "swapType", "combinedAmountOut" ], "not": { "required": [ "leaderAmountIn" ] } } ] }, "examples": { "exactInputDry": { "summary": "Dry quote for an exact input", "value": { "sourceAssetId": "nep141:wrap.near", "destinationAssetId": "nep141:usdc.near", "dry": true, "swapType": "EXACT_INPUT", "leaderAmountIn": "407706057266639649073549", "slippageToleranceBps": 100, "appFees": [], "executionMode": "partner-managed" } }, "exactOutputDry": { "summary": "Dry quote for an exact output", "value": { "sourceAssetId": "nep141:wrap.near", "destinationAssetId": "nep141:usdc.near", "dry": true, "swapType": "EXACT_OUTPUT", "combinedAmountOut": "4000000", "slippageToleranceBps": 100, "appFees": [], "executionMode": "partner-managed" } } } } } }, "CopyTradeSubmitRequest": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "tradeId", "executionMode" ], "properties": { "tradeId": { "type": "string", "description": "Hitch trade ID returned by /copy-trades/prepare." }, "executionMode": { "$ref": "#/components/schemas/ExecutionMode" }, "partnerQuote": { "type": "object", "required": [ "request", "response" ], "properties": { "request": { "$ref": "#/components/schemas/OneClickQuoteRequest" }, "response": { "$ref": "#/components/schemas/OneClickQuoteResponse" } }, "additionalProperties": false }, "signedLeaderIntent": { "$ref": "#/components/schemas/SignedIntent", "description": "Leader signature over the exact contribution intent returned by /copy-trades/prepare or by the first partner-managed submit response." } }, "additionalProperties": false }, "examples": { "hitchManaged": { "summary": "Hitch-managed: submit the Leader signature", "value": { "tradeId": "550e8400-e29b-41d4-a716-446655440021", "executionMode": "hitch-managed", "signedLeaderIntent": { "standard": "nep413", "payload": { "recipient": "intents.near", "nonce": "AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8=", "message": "{\"signer_id\":\"0x5870000000000000000000000000000019b5\",\"verifying_contract\":\"intents.near\",\"intents\":[{\"intent\":\"transfer\"}]}" }, "public_key": "ed25519:ExamplePublicKeyBase58", "signature": "ed25519:ExampleSignatureBase58" } } }, "partnerQuote": { "summary": "Partner-managed: hand off signed live 1Click quote", "description": "The partner obtains this non-dry quote with its own JWT. Hitch returns the exact Leader contribution intent to sign. Do not send the partner JWT.", "value": { "tradeId": "550e8400-e29b-41d4-a716-446655440021", "executionMode": "partner-managed", "partnerQuote": { "request": { "dry": false, "swapType": "EXACT_INPUT", "originAsset": "nep141:wrap.near", "destinationAsset": "nep141:usdc.near", "amount": "1215906057266639649073549", "recipient": "0xescrow_example", "refundTo": "0xescrow_example" }, "response": { "signature": "provider_quote_signature", "timestamp": "2026-10-09T12:00:00.000Z", "correlationId": "550e8400-e29b-41d4-a716-446655440001", "quoteRequest": { "dry": false, "swapType": "EXACT_INPUT", "originAsset": "nep141:wrap.near", "destinationAsset": "nep141:usdc.near", "amount": "1215906057266639649073549", "recipient": "0xescrow_example", "refundTo": "0xescrow_example" }, "quote": { "amountIn": "1215906057266639649073549", "amountOut": "6115600", "depositAddress": "0xdeposit_example", "deadline": "2026-10-09T13:00:00.000Z" } } } } }, "partnerLeaderAuthorization": { "summary": "Partner-managed: submit the Leader signature", "description": "After the quote handoff, sign the returned leaderIntent and call again with signedLeaderIntent; the partnerQuote is no longer needed.", "value": { "tradeId": "550e8400-e29b-41d4-a716-446655440021", "executionMode": "partner-managed", "signedLeaderIntent": { "standard": "erc191", "payload": "{\"signer_id\":\"0x5870000000000000000000000000000019b5\",\"verifying_contract\":\"intents.near\",\"intents\":[{\"intent\":\"transfer\"}]}", "signature": "secp256k1:ExampleSignatureBase58" } } } } } } } }, "schemas": { "WalletType": { "type": "string", "enum": [ "evm", "near", "solana", "passkey" ], "description": "Signer family, independent of the wallet app or connection transport. WalletConnect uses `evm` or `solana` according to the connected chain namespace." }, "Role": { "type": "string", "enum": [ "LEADER", "FOLLOWER" ], "description": "Verified wallet role returned in the top-level wallet session response." }, "ExecutionMode": { "type": "string", "enum": [ "hitch-managed", "partner-managed" ], "description": "Whether Hitch or the partner calls 1Click using its own server-side JWT." }, "WalletProof": { "type": "object", "required": [ "signature" ], "properties": { "standard": { "type": "string", "enum": [ "erc191", "raw_ed25519", "nep413", "webauthn" ], "description": "Optional normalized proof format when sending the standard/payload/signature envelope." }, "payload": { "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/IntentsNep413Payload" } ] }, "publicKey": { "type": "string", "description": "Wallet or passkey public key when required." }, "public_key": { "type": "string", "description": "Normalized signature-envelope public key when required." }, "accountId": { "type": "string", "description": "NEAR account ID; defaults to the verified wallet address." }, "credentialId": { "type": "string", "description": "Optional assertion credential ID encoded as base64url; not required when the challenge is already bound to the passkey public key." }, "clientDataJSON": { "type": "string", "description": "Base64url-encoded UTF-8 clientDataJSON returned by AuthenticatorAssertionResponse." }, "client_data_json": { "type": "string" }, "authenticatorData": { "type": "string", "description": "Base64url-encoded authenticatorData returned by AuthenticatorAssertionResponse." }, "authenticator_data": { "type": "string" }, "signature": { "type": "string", "description": "Wallet-specific signature. Solana raw signatures are base64; EVM personal-sign signatures use 0x hex; NEAR signatures use the NEP-413 encoding; passkeys provide the WebAuthn assertion signature." } }, "additionalProperties": true }, "WalletChallenge": { "type": "object", "required": [ "challengeId", "walletType", "walletAddress", "intentsAccountId", "message", "expiresAt", "signatureStandard", "standard" ], "properties": { "challengeId": { "type": "string", "description": "Opaque, one-time challenge identifier.", "format": "uuid" }, "walletType": { "$ref": "#/components/schemas/WalletType" }, "walletAddress": { "type": "string", "description": "Connected signer identity being verified." }, "intentsAccountId": { "type": "string", "description": "Intents signer/account ID resolved from the connected signer identity." }, "message": { "type": "string", "description": "Exact text to sign for EVM, Solana, and NEAR wallets. Passkeys use a base64url SHA-256 challenge derived from this message, unless the combined balance-authorization payload is returned." }, "expiresAt": { "type": "string", "format": "date-time", "description": "Challenge expiration in UTC." }, "signatureStandard": { "type": "string", "description": "Wallet signature format expected by the verifier.", "enum": [ "erc191", "raw_ed25519", "nep413", "webauthn" ] }, "webauthnRequestOptions": { "type": "object", "required": [ "challenge", "rpId", "timeout", "userVerification" ], "properties": { "challenge": { "type": "string", "description": "Base64url challenge bytes for navigator.credentials.get()." }, "rpId": { "type": "string", "description": "Registered relying-party domain for the partner origin." }, "timeout": { "type": "integer", "description": "WebAuthn assertion timeout in milliseconds." }, "userVerification": { "type": "string", "enum": [ "required", "preferred", "discouraged" ], "description": "Authenticator user-verification preference." }, "allowCredentials": { "type": "array", "items": { "type": "object", "properties": { "type": { "const": "public-key" }, "id": { "type": "string", "description": "Base64url credential ID." } }, "required": [ "type", "id" ], "additionalProperties": false }, "description": "Present only when the request selected a known credential; omit for discoverable credentials." } }, "additionalProperties": false, "description": "WebAuthn options for the already-connected passkey signer; the partner wallet runs navigator.credentials.get() and returns its assertion." }, "standard": { "type": "string", "enum": [ "erc191", "raw_ed25519", "nep413", "webauthn" ], "description": "Present on every response. Identifies the signer format, or the format of the optional balance-authorization payload." }, "payload": { "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/IntentsNep413Payload" } ], "description": "Optional read-only Intents balance-authorization payload returned only when includeBalances is true. For a passkey in the combined flow, webauthnRequestOptions.challenge is derived from this exact payload." }, "nonce": { "type": "string", "description": "NEAR wallet nonce returned alongside the challenge message." }, "recipient": { "type": "string", "description": "NEP-413 recipient (the application host); returned for NEAR wallet challenges." } }, "additionalProperties": false }, "WalletSession": { "type": "object", "required": [ "verified", "role", "walletType", "walletAddress", "intentsAccountId", "sessionId", "expiresAt", "account" ], "properties": { "verified": { "const": true }, "role": { "$ref": "#/components/schemas/Role" }, "walletType": { "$ref": "#/components/schemas/WalletType" }, "walletAddress": { "type": "string" }, "intentsAccountId": { "type": "string", "description": "NEAR Intents account derived from the verified signer." }, "sessionId": { "type": "string", "format": "uuid" }, "expiresAt": { "type": "string", "format": "date-time" }, "sessionToken": { "type": "string", "description": "Returned only for partner-key server requests. Keep secret and short-lived." }, "tokenType": { "const": "Bearer" }, "account": { "$ref": "#/components/schemas/Account" } }, "additionalProperties": true }, "Account": { "type": "object", "required": [ "accountId", "walletType", "walletAddress", "role", "verifiedAt" ], "properties": { "accountId": { "type": "string" }, "walletType": { "$ref": "#/components/schemas/WalletType" }, "walletAddress": { "type": "string" }, "role": { "type": "string", "enum": [ "leader", "follower" ] }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": false }, "Balance": { "type": "object", "required": [ "assetId", "symbol", "blockchain", "decimals", "amount", "formattedAmount" ], "properties": { "assetId": { "type": "string" }, "symbol": { "type": "string", "description": "Display ticker; NEAR is displayed as NEAR even when its Intents representation is wrapped NEAR." }, "blockchain": { "type": "string" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 36 }, "amount": { "type": "string", "pattern": "^\\d+$", "description": "Exact token amount in base units." }, "formattedAmount": { "type": [ "string", "null" ], "description": "Human-readable rendering for display; do math with amount." } }, "additionalProperties": true }, "BalanceList": { "type": "object", "required": [ "accountId", "balances" ], "properties": { "accountId": { "type": "string" }, "balances": { "type": "array", "items": { "$ref": "#/components/schemas/Balance" } } }, "additionalProperties": true }, "Asset": { "type": "object", "required": [ "assetId", "symbol", "name", "decimals", "network", "canonical", "sources" ], "properties": { "assetId": { "type": "string", "description": "Provider asset identifier; use exactly this value in quotes." }, "symbol": { "type": "string", "description": "Display ticker." }, "name": { "type": "string", "description": "Human-readable asset name." }, "decimals": { "type": "integer", "description": "Token decimals for converting base-unit strings." }, "network": { "type": "string", "description": "Network where this asset representation lives." }, "canonical": { "type": "boolean", "description": "True when this is Hitch's selected Intents representation for the ticker." }, "priceUsd": { "type": "string", "description": "Recent indicative USD price; not a guaranteed execution price." }, "priceUpdatedAt": { "type": "string", "format": "date-time", "description": "Timestamp of the USD price sample." }, "sources": { "type": "array", "description": "Matching external-network token representations that can be used as deposit sources, ordered by price freshness and preferred network.", "items": { "$ref": "#/components/schemas/AssetSource" } } }, "additionalProperties": false }, "AssetSource": { "type": "object", "required": [ "assetId", "network", "symbol", "decimals", "priceFresh" ], "properties": { "assetId": { "type": "string", "description": "1Click asset ID for the external source representation." }, "network": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "integer" }, "priceUsd": { "type": "string" }, "priceUpdatedAt": { "type": "string", "format": "date-time" }, "priceFresh": { "type": "boolean", "description": "Whether this source token's price sample is less than five minutes old." } }, "additionalProperties": false }, "AssetList": { "type": "object", "required": [ "assets" ], "properties": { "assets": { "type": "array", "items": { "$ref": "#/components/schemas/Asset" } } }, "additionalProperties": false }, "AppFee": { "$ref": "#/components/schemas/OneClickAppFee", "description": "1Click app fee entry; fee is expressed in basis points." }, "DepositSource": { "type": "object", "required": [ "assetId", "network", "symbol", "decimals", "amount" ], "properties": { "assetId": { "type": "string" }, "network": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "integer" }, "amount": { "type": [ "string", "null" ], "description": "Source amount in base units; null in the first-party flexible-deposit address-only flow." } }, "additionalProperties": true }, "DepositDestination": { "type": "object", "required": [ "assetId", "accountId", "symbol", "decimals" ], "properties": { "assetId": { "type": "string" }, "accountId": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "integer" } }, "additionalProperties": true }, "DepositInstructions": { "oneOf": [ { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string" }, "memo": { "type": [ "string", "null" ] }, "minimumAmount": { "type": [ "string", "null" ] }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": false }, { "type": "null" } ] }, "DepositQuoteResult": { "type": "object", "required": [ "executionMode", "source", "destination" ], "properties": { "quoteId": { "type": "string", "format": "uuid", "description": "Hitch-generated ID for Hitch-managed deposits. Use this to query Hitch status or submit a source transaction. It is distinct from 1Click correlationId. Omitted for partner-managed quote templates." }, "correlationId": { "type": [ "string", "null" ], "description": "1Click provider correlation ID when a live quote was obtained. It is distinct from Hitch quoteId." }, "executionMode": { "$ref": "#/components/schemas/ExecutionMode" }, "source": { "$ref": "#/components/schemas/DepositSource" }, "destination": { "$ref": "#/components/schemas/DepositDestination" }, "quoteRequest": { "oneOf": [ { "$ref": "#/components/schemas/OneClickQuoteRequest" }, { "type": "null" } ], "description": "Normalized 1Click request/template. Hitch-managed responses include the concrete request." }, "quoteResponse": { "oneOf": [ { "$ref": "#/components/schemas/OneClickQuoteResponse" }, { "type": "null" } ], "description": "Full signed 1Click response for Hitch-managed quotes; null for partner-managed mode." }, "deposit": { "$ref": "#/components/schemas/DepositInstructions" }, "nextStep": { "type": "string" }, "status": { "type": "string" }, "minimumAmount": { "type": [ "string", "null" ] }, "deadline": { "type": "string", "format": "date-time" }, "id": { "type": "string", "description": "Legacy first-party preview alias for quoteId." }, "depositAddress": { "type": "string" }, "depositMemo": { "type": [ "string", "null" ] }, "assetId": { "type": "string" }, "sourceAssetId": { "type": "string" }, "destinationAssetId": { "type": "string" }, "symbol": { "type": "string" }, "blockchain": { "type": "string" }, "decimals": { "type": "integer" } }, "additionalProperties": true }, "DepositStatus": { "type": "object", "required": [ "status", "updatedAt", "transactionHashes" ], "properties": { "status": { "type": "string", "description": "Current 1Click status; provider status values are preserved." }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "transactionHashes": { "type": "array", "items": { "type": "object", "required": [ "hash", "explorerUrl" ], "properties": { "hash": { "type": "string" }, "explorerUrl": { "type": [ "string", "null" ], "format": "uri" } }, "additionalProperties": false } } }, "additionalProperties": false }, "Leader": { "type": "object", "required": [ "leaderAccountId", "feeBps", "feeChangePending", "registeredAt" ], "properties": { "leaderAccountId": { "type": "string", "description": "Leader Intents account ID." }, "feeBps": { "type": "integer", "minimum": 0, "maximum": 25, "description": "Current fee in basis points." }, "feeChangePending": { "type": "boolean", "description": "Whether any active follower still needs to reconfirm the fee." }, "registeredAt": { "type": "string", "format": "date-time", "description": "Leader registration time." }, "activeFollowerCount": { "type": "integer", "description": "Number of eligible active followers." }, "completedTradeCount": { "type": "integer", "description": "Count of successful copied trades." }, "walletType": { "$ref": "#/components/schemas/WalletType", "description": "Signer family for the leader account; clients should not infer it from the Intents account ID." } }, "additionalProperties": false }, "LeaderList": { "type": "object", "required": [ "leaders" ], "properties": { "leaders": { "type": "array", "items": { "type": "object", "required": [ "accountId", "blockchain", "copyTradingFeeBps", "followerCount", "successfulTradeCount", "createdAt" ], "properties": { "accountId": { "type": "string" }, "blockchain": { "type": [ "string", "null" ] }, "copyTradingFeeBps": { "type": "integer" }, "copyTradingFeeVersion": { "type": "integer" }, "followerCount": { "type": "integer" }, "successfulTradeCount": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" } }, "additionalProperties": true } } }, "additionalProperties": true }, "LeaderFeeUpdate": { "type": "object", "required": [ "leaderAccountId", "feeBps", "followersRequiringConfirmation", "copyTradingEnabledFollowerCount" ], "properties": { "leaderAccountId": { "type": "string", "description": "Updated leader account ID." }, "feeBps": { "type": "integer", "description": "New fee for future trades." }, "followersRequiringConfirmation": { "type": "integer", "description": "Followers not yet opted in to the new fee." }, "copyTradingEnabledFollowerCount": { "type": "integer", "description": "Followers currently eligible for copy trades." }, "message": { "type": "string", "description": "Human-readable explanation of the change." } }, "additionalProperties": false }, "Follower": { "type": "object", "required": [ "followerAccountId", "status", "feeConfirmed", "copiedTradeCount", "followedAt" ], "properties": { "followerAccountId": { "type": "string", "description": "Public Intents account ID of the follower." }, "status": { "type": "string", "enum": [ "ACTIVE", "AWAITING_FEE_CONFIRMATION", "INACTIVE", "PROCESSING" ], "description": "Relationship state. Only active, confirmed followers are eligible for sizing." }, "feeConfirmed": { "type": "boolean", "description": "Whether this follower consented to the current leader fee." }, "copiedTradeCount": { "type": "integer", "description": "Successful copied trades for this relationship." }, "followedAt": { "type": "string", "format": "date-time", "description": "Relationship creation time." } }, "additionalProperties": false }, "FollowerList": { "type": "object", "required": [ "leaderAccountId", "followers" ], "properties": { "leaderAccountId": { "type": "string" }, "followers": { "type": "array", "items": { "type": "object", "required": [ "accountId", "copiedTradeCount", "walletType", "feeConfirmed" ], "properties": { "accountId": { "type": "string" }, "copiedTradeCount": { "type": "integer" }, "walletType": { "type": [ "string", "null" ], "enum": [ "evm", "near", "solana", "passkey", "tron", null ] }, "feeConfirmed": { "type": "boolean" } }, "additionalProperties": true } } }, "additionalProperties": true }, "SignedIntent": { "type": "object", "required": [ "standard", "payload", "signature" ], "properties": { "standard": { "type": "string", "description": "Signature standard selected by the verified wallet: EVM uses erc191, Solana uses raw_ed25519, NEAR uses nep413, and passkeys use webauthn.", "enum": [ "nep413", "erc191", "raw_ed25519", "webauthn" ] }, "payload": { "oneOf": [ { "$ref": "#/components/schemas/IntentsNep413Payload" }, { "type": "string" } ], "description": "Exact payload returned for the pending operation. NEP-413 uses an envelope object; ERC-191, raw Ed25519, and WebAuthn use the exact serialized operation payload string. Preserve bytes and field casing." }, "public_key": { "type": "string", "description": "Public key used to verify the signature, if required by the standard." }, "signature": { "type": "string", "description": "Signature in the encoding required by the selected standard: secp256k1: for EVM, ed25519: for Solana/NEAR, or the passkey curve prefix plus base58 signature for WebAuthn." }, "client_data_json": { "type": "string", "description": "Base64url WebAuthn clientDataJSON when signing with a passkey." }, "authenticator_data": { "type": "string", "description": "Base64url WebAuthn authenticatorData when signing with a passkey." } }, "additionalProperties": false }, "WalletAuthorization": { "type": "object", "required": [ "followId", "status", "leaderAccountId", "feeBps", "authorization", "expiresAt" ], "properties": { "followId": { "type": "string", "description": "Pending follow relationship/operation ID." }, "status": { "type": "string", "enum": [ "AWAITING_SIGNATURE", "PROCESSING" ], "description": "Operation state." }, "leaderAccountId": { "type": "string", "description": "Leader account the follower selected." }, "feeBps": { "type": "integer", "description": "Fee presented for follower consent." }, "authorization": { "type": "object", "required": [ "standard", "payload" ], "properties": { "standard": { "type": "string", "description": "Signature standard expected from the connected wallet." }, "payload": { "description": "Exact authorization envelope to sign: NEP-413 object for NEAR, exact serialized Intents payload string for EVM and Solana, or the payload string used as the WebAuthn challenge for passkeys.", "oneOf": [ { "$ref": "#/components/schemas/IntentsNep413Payload" }, { "type": "string" } ] } }, "additionalProperties": false }, "expiresAt": { "type": "string", "format": "date-time", "description": "Payload expiration." } }, "additionalProperties": false }, "OperationStatus": { "type": "object", "required": [ "operationId", "status", "updatedAt" ], "properties": { "operationId": { "type": "string", "description": "Operation ID." }, "status": { "type": "string", "enum": [ "PROCESSING", "SUCCESS", "FAILED", "RECOVERY_REQUIRED" ], "description": "Reconciled lifecycle state." }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last reconciliation time." } }, "additionalProperties": false }, "QuoteAssetAmount": { "type": "object", "required": [ "amountIn", "estimatedAmountOut" ], "properties": { "amountIn": { "type": "string", "description": "Quoted source input in base units; for EXACT_OUTPUT this is the input needed to target the output amount." }, "estimatedAmountOut": { "type": "string", "description": "Indicative output in destination-token base units." }, "minAmountOut": { "type": "string", "description": "Optional minimum destination amount, generally returned for EXACT_INPUT quotes." }, "minAmountIn": { "type": "string", "description": "Optional minimum accepted source amount, generally returned for EXACT_OUTPUT quotes." } }, "additionalProperties": false }, "SingleQuoteResult": { "type": "object", "required": [ "quoteId", "correlationId", "executionMode", "sourceAsset", "destinationAsset", "swapType", "amountIn", "amountOut", "slippageToleranceBps", "deadline", "expiresAt", "appFees", "quoteRequest", "quoteResponse", "status" ], "properties": { "quoteId": { "type": "string", "format": "uuid", "description": "Hitch-generated quote lifecycle ID used with /swaps/submit and /swaps/{swapId}." }, "correlationId": { "type": [ "string", "null" ], "description": "1Click provider correlation ID for its own diagnostics; not the Hitch quoteId." }, "executionMode": { "$ref": "#/components/schemas/ExecutionMode" }, "sourceAsset": { "$ref": "#/components/schemas/QuoteAssetIdentity" }, "destinationAsset": { "$ref": "#/components/schemas/QuoteAssetIdentity" }, "swapType": { "type": "string", "enum": [ "EXACT_INPUT", "EXACT_OUTPUT" ] }, "amountIn": { "type": "string", "description": "Quoted source amount in base units." }, "amountOut": { "type": "string", "description": "Quoted destination amount in base units; equals requested amountOut for EXACT_OUTPUT." }, "minAmountOut": { "type": [ "string", "null" ] }, "minAmountIn": { "type": [ "string", "null" ] }, "slippageToleranceBps": { "type": "integer" }, "deadline": { "type": "string", "format": "date-time", "description": "Hitch sets the 1Click deadline to one hour after quote creation." }, "expiresAt": { "type": "string", "format": "date-time" }, "appFees": { "type": "array", "items": { "$ref": "#/components/schemas/AppFee" } }, "quoteRequest": { "$ref": "#/components/schemas/OneClickQuoteRequest" }, "quoteResponse": { "$ref": "#/components/schemas/OneClickQuoteResponse" }, "intent": { "oneOf": [ { "$ref": "#/components/schemas/SignedIntent" }, { "type": "null" } ], "description": "Unsigned operation-specific payload to sign; present only for a live quote." }, "status": { "type": "string", "enum": [ "QUOTED", "AWAITING_SIGNATURE" ] } }, "additionalProperties": false }, "ExpectedFee": { "type": "object", "required": [ "amount", "assetId", "symbol", "decimals", "rounding" ], "properties": { "amount": { "type": "string", "description": "Estimated fee in destination-token base units: floor(eligible followers’ projected gross output × feeBps ÷ 10,000). For example, 2.0658 USDC × 10 bps = 0.0020658 USDC, rounded down to 0.002065 USDC (2065 base units at 6 decimals)." }, "assetId": { "type": "string", "description": "Destination fee asset ID." }, "symbol": { "type": "string", "description": "Destination display ticker." }, "decimals": { "type": "integer", "description": "Destination token decimal count." }, "rounding": { "type": "string", "description": "Fee rounds down to the smallest destination unit." } }, "additionalProperties": false }, "QuoteAssetIdentity": { "type": "object", "required": [ "assetId", "symbol", "decimals" ], "properties": { "assetId": { "type": "string", "description": "Canonical Intents asset identifier." }, "symbol": { "type": "string", "description": "Display ticker." }, "decimals": { "type": "integer", "description": "Token precision for base-unit amounts." } }, "additionalProperties": false }, "CopyTrade": { "type": "object", "required": [ "tradeId", "status", "providerStatus", "needsLeaderAuthorization", "leaderIntent", "actionRequired", "relayStatus", "acceptedQuote", "settledAmountOut", "confirmedRefund", "updatedAt" ], "properties": { "tradeId": { "type": "string", "description": "Hitch trade identifier." }, "status": { "type": "string", "enum": [ "CREATED", "AWAITING_LEADER_AUTHORIZATION", "COLLECTING_CONTRIBUTIONS", "CANCEL_REQUESTED", "QUOTE_REQUESTING", "SWAP_SUBMITTED", "PROCESSING", "PAYOUT_PENDING", "REFUND_PENDING", "SUCCESS", "REFUNDED", "RECOVERY_REQUIRED", "CANCELLED" ], "description": "Current reconciled copy-trade lifecycle status." }, "providerStatus": { "type": [ "string", "null" ], "description": "Latest status reported by 1Click, when a provider operation exists." }, "needsLeaderAuthorization": { "type": "boolean", "description": "Whether the Leader must sign or resubmit the contribution authorization." }, "leaderIntent": { "type": [ "object", "null" ], "description": "Leader-specific intent payload, returned to the Leader when authorization is needed.", "additionalProperties": true }, "actionRequired": { "type": [ "string", "null" ], "description": "Next server action or status to wait for, if any." }, "relayStatus": { "type": [ "string", "null" ], "description": "Latest transfer relay state, when applicable." }, "acceptedQuote": { "type": [ "object", "null" ], "description": "Live 1Click quote amounts visible only to the Leader.", "properties": { "amountIn": { "type": [ "string", "null" ], "description": "Accepted source amount in base units." }, "amountOut": { "type": [ "string", "null" ], "description": "Accepted destination amount in base units." }, "minAmountOut": { "type": [ "string", "null" ], "description": "Minimum destination amount in base units." } }, "additionalProperties": false }, "settledAmountOut": { "type": [ "string", "null" ], "description": "Confirmed total destination output, visible only to the Leader. For EXACT_OUTPUT it must match requestedAmountOut before payout allocation." }, "confirmedRefund": { "type": [ "string", "null" ], "description": "Confirmed source-asset refund visible only to the Leader." }, "quoteId": { "type": "string", "description": "Hitch quote ID used to initiate this public API trade, when applicable." }, "executionMode": { "$ref": "#/components/schemas/ExecutionMode" }, "swapType": { "type": "string", "enum": [ "EXACT_INPUT", "EXACT_OUTPUT" ], "description": "Swap mode used for this copied trade, when the quote came through the public API." }, "requestedAmountOut": { "type": "string", "description": "Fixed combined destination output target in destination base units for EXACT_OUTPUT trades." }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last reconciliation update." } }, "additionalProperties": true }, "CopyTradeList": { "type": "object", "required": [ "items", "nextCursor", "refreshableTrades" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "tradeId", "status", "role", "sourceAssetId", "sourceDecimals", "sourceContribution", "destinationAssetId", "destinationDecimals", "settledOutput", "refundAllocation", "confirmedRefund", "createdAt" ], "properties": { "tradeId": { "type": "string", "description": "Hitch trade ID." }, "status": { "type": "string", "description": "Current persisted trade status." }, "role": { "type": "string", "enum": [ "LEADER", "FOLLOWER" ], "description": "Current account's role in this trade." }, "sourceAssetId": { "type": "string", "description": "Source token asset ID." }, "sourceDecimals": { "type": "integer", "description": "Source token decimal count." }, "sourceContribution": { "type": "string", "description": "Current account's source contribution in base units." }, "destinationAssetId": { "type": "string", "description": "Destination asset ID." }, "destinationDecimals": { "type": "integer", "description": "Destination token decimal count." }, "settledOutput": { "type": [ "string", "null" ], "description": "Current account's allocated destination output in base units, when settled." }, "refundAllocation": { "type": [ "string", "null" ], "description": "Current account's allocated source refund in base units, when available." }, "confirmedRefund": { "type": [ "string", "null" ], "description": "Current account's confirmed source refund in base units." }, "createdAt": { "type": "string", "format": "date-time", "description": "Trade creation time." } }, "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page. Pass it back as-is on the next request." }, "refreshableTrades": { "type": "array", "description": "Active trades whose status should be refreshed by trade ID.", "items": { "type": "object", "required": [ "tradeId", "status" ], "properties": { "tradeId": { "type": "string" }, "status": { "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false }, "Swap": { "type": "object", "required": [ "swapId", "status", "sourceAssetId", "amountIn", "destinationAssetId", "estimatedAmountOut", "minAmountOut", "submittedAt" ], "properties": { "swapId": { "type": "string", "description": "Hitch swap identifier." }, "status": { "type": "string", "enum": [ "PROCESSING", "SUCCESS", "REFUNDED", "FAILED", "RECOVERY_REQUIRED" ], "description": "Reconciled lifecycle state." }, "sourceAssetId": { "type": "string", "description": "Input asset ID." }, "amountIn": { "type": "string", "description": "Input in base units." }, "destinationAssetId": { "type": "string", "description": "Output asset ID." }, "estimatedAmountOut": { "type": "string", "description": "Dry quote estimate." }, "minAmountOut": { "type": "string", "description": "Live quote minimum receive threshold." }, "settledAmountOut": { "type": "string", "description": "Balance-confirmed output, present after settlement." }, "submittedAt": { "type": "string", "format": "date-time", "description": "Submission time." }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last reconciliation update." } }, "additionalProperties": false }, "ApiError": { "type": "object", "required": [ "error", "message", "requestId" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Safe user-facing explanation; never includes signatures, secrets, or confidential balances." }, "requestId": { "type": "string", "description": "Support correlation ID." }, "details": { "type": "object", "description": "Optional field-level validation details." } }, "additionalProperties": false }, "OneClickAppFee": { "type": "object", "required": [ "recipient", "fee" ], "properties": { "recipient": { "type": "string", "description": "Recipient address/account for the application fee." }, "fee": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Application fee in basis points (1 bps = 0.01%); provider limits apply." } }, "additionalProperties": false }, "OneClickQuoteRequest": { "type": "object", "required": [ "dry", "swapType", "slippageTolerance", "originAsset", "depositType", "destinationAsset", "amount", "refundTo", "refundType", "recipient", "recipientType", "deadline" ], "properties": { "dry": { "type": "boolean", "description": "True simulates and validates a quote without creating a deposit address or starting execution." }, "swapType": { "type": "string", "enum": [ "EXACT_INPUT", "EXACT_OUTPUT", "FLEX_INPUT" ], "description": "EXACT_INPUT fixes the source amount; EXACT_OUTPUT fixes the destination amount; FLEX_INPUT allows a provider-defined input range." }, "slippageTolerance": { "type": "integer", "minimum": 0, "description": "Maximum slippage in basis points (100 = 1%)." }, "originAsset": { "type": "string", "description": "Exact source 1Click assetId." }, "depositType": { "type": "string", "enum": [ "ORIGIN_CHAIN", "CONFIDENTIAL_INTENTS", "CONFIDENTIAL_INTENTS" ], "description": "Hitch sets INTENTS for swap and copy-trade quotes. Source-chain deposits use ORIGIN_CHAIN." }, "destinationAsset": { "type": "string", "description": "Exact destination 1Click assetId." }, "amount": { "type": "string", "pattern": "^[0-9]+$", "description": "Amount in base units: source amount for EXACT_INPUT, destination target for EXACT_OUTPUT." }, "refundTo": { "type": "string", "description": "Hitch-selected Intents refund account for swap and copy-trade quotes; not an app-supplied value." }, "refundType": { "type": "string", "enum": [ "ORIGIN_CHAIN", "CONFIDENTIAL_INTENTS", "CONFIDENTIAL_INTENTS" ], "description": "Hitch sets INTENTS for swap and copy-trade quotes." }, "recipient": { "type": "string", "description": "Hitch-selected Intents destination for swap and copy-trade quotes; not an app-supplied value." }, "recipientType": { "type": "string", "enum": [ "DESTINATION_CHAIN", "CONFIDENTIAL_INTENTS", "CONFIDENTIAL_INTENTS" ], "description": "Hitch sets INTENTS for swap and copy-trade quotes." }, "deadline": { "type": "string", "format": "date-time", "description": "Hitch sets this to one hour after quote creation for swap and copy-trade quotes." }, "depositMode": { "type": "string", "enum": [ "SIMPLE", "MEMO" ], "default": "SIMPLE", "description": "Hitch sets SIMPLE for swap and copy-trade quotes." }, "confidentiality": { "type": "string", "enum": [ "public", "basic", "advanced" ], "description": "Hitch sets basic for swap and copy-trade quotes.", "default": "basic" }, "appFees": { "type": "array", "items": { "$ref": "#/components/schemas/OneClickAppFee" }, "description": "Optional application fee recipients and rates." }, "referral": { "type": "string", "description": "Hitch sets hitch for attribution on swap and copy-trade quotes.", "default": "hitch" }, "quoteWaitingTimeMs": { "type": "integer", "minimum": 0, "description": "Optional quote collection wait time in milliseconds." }, "insured": { "type": "boolean", "description": "Optional provider insurance flag; may add a provider fee." }, "connectedWallets": { "type": "array", "items": { "type": "string" }, "description": "Hitch supplies the connected signer wallet for swap and copy-trade quotes." }, "sessionId": { "type": "string", "description": "Hitch-generated session ID for swap and copy-trade quotes." } }, "additionalProperties": true, "description": "Normalized 1Click request. Optional provider fields may evolve; consult the linked 1Click API reference for its authoritative schema." }, "OneClickQuote": { "type": "object", "required": [ "amountIn", "amountOut" ], "properties": { "amountIn": { "type": "string", "description": "Quoted source amount in base units." }, "amountInFormatted": { "type": "string", "description": "Display-only source amount." }, "amountInUsd": { "type": "string", "description": "Provider estimate of source USD value." }, "minAmountIn": { "type": "string", "description": "Minimum accepted source amount for EXACT_OUTPUT and quote types that return an input threshold." }, "amountOut": { "type": "string", "description": "Estimated destination amount in base units; not settled output." }, "amountOutFormatted": { "type": "string", "description": "Display-only destination amount." }, "amountOutUsd": { "type": "string", "description": "Provider estimate of destination USD value." }, "minAmountOut": { "type": "string", "description": "Minimum destination amount for EXACT_INPUT and flexible quote types that return an output threshold." }, "timeEstimate": { "type": "integer", "description": "Estimated execution time in seconds, when supplied." }, "depositAddress": { "type": "string", "description": "Funding address for a live quote; omitted from dry quotes." }, "depositMemo": { "type": "string", "description": "Required source-chain memo/tag, when supplied." }, "deadline": { "type": "string", "format": "date-time", "description": "Provider quote deadline." }, "timeWhenInactive": { "type": "string", "format": "date-time", "description": "Provider inactivity/refund time, when supplied." } }, "additionalProperties": true }, "OneClickQuoteResponse": { "type": "object", "required": [ "correlationId", "timestamp", "signature", "quoteRequest", "quote" ], "properties": { "correlationId": { "type": "string", "description": "Provider trace ID for support and diagnostics." }, "timestamp": { "type": "string", "format": "date-time", "description": "Provider timestamp included in signature verification." }, "signature": { "type": "string", "description": "1Click signature over the quote request/response snapshot; verify before trusting provider fields." }, "quoteRequest": { "$ref": "#/components/schemas/OneClickQuoteRequest", "description": "Request echoed by 1Click; compare assets, amount, recipients, refund, slippage, and deadline." }, "quote": { "$ref": "#/components/schemas/OneClickQuote", "description": "Pricing and, for live quotes, deposit instructions." } }, "additionalProperties": true, "description": "Full 1Click quote response. Preserve it intact and verify its signature before use." }, "IntentsNep413Payload": { "type": "object", "required": [ "recipient", "nonce", "message" ], "properties": { "recipient": { "type": "string", "description": "NEP-413 recipient; for Intents this is typically intents.near." }, "nonce": { "type": "string", "description": "Base64 nonce required by NEP-413. Preserve the exact value returned by the wallet authorization step." }, "message": { "type": "string", "description": "Exact UTF-8 JSON message the wallet signs. Do not parse and reserialize it after signing." } }, "additionalProperties": false }, "CopyTradeQuote": { "type": "object", "required": [ "quoteId", "executionMode", "swapType", "feeBps", "sourceAsset", "destinationAsset", "leader", "followers", "combined", "expectedFee", "expiresAt", "nextStep" ], "properties": { "quoteId": { "type": "string", "description": "Hitch quote ID; use it when creating a trade before the quote expires.", "format": "uuid" }, "executionMode": { "$ref": "#/components/schemas/ExecutionMode" }, "feeBps": { "type": "integer", "description": "Leader fee rate snapshotted for this quote." }, "sourceAsset": { "$ref": "#/components/schemas/QuoteAssetIdentity" }, "destinationAsset": { "$ref": "#/components/schemas/QuoteAssetIdentity" }, "leader": { "type": "object", "required": [ "amountIn", "estimatedAmountOut" ], "properties": { "amountIn": { "type": "string", "description": "Leader contribution in source-token base units; in EXACT_OUTPUT mode this is the leader allocation within the pooled source input." }, "estimatedAmountOut": { "type": "string", "description": "Leader projected net destination output after its contribution share is allocated and the leader fee is withheld from follower output." }, "minAmountOut": { "type": "string", "description": "Optional minimum destination amount, generally returned for EXACT_INPUT quotes." }, "minAmountIn": { "type": "string", "description": "Optional minimum accepted source amount, generally returned for EXACT_OUTPUT quotes." } }, "additionalProperties": false }, "followers": { "type": "object", "required": [ "eligibleCount", "excludedCount", "amountIn", "estimatedGrossOutput" ], "properties": { "eligibleCount": { "type": "integer", "description": "Followers eligible under current balance, $1 contribution threshold, and fee consent." }, "excludedCount": { "type": "integer", "description": "Followers excluded from this quote. No individual balance or address is disclosed." }, "amountIn": { "type": "string", "description": "Aggregate follower contribution in source base units." }, "estimatedGrossOutput": { "type": "string", "description": "Projected gross output for eligible followers before the Leader fee, allocated by their contribution shares." }, "activeCount": { "type": "integer", "description": "Active follower relationships considered before balance, minimum and fee-consent eligibility checks." } }, "additionalProperties": false }, "combined": { "type": "object", "required": [ "amountIn", "estimatedAmountOut", "quoteRequest", "quoteResponse" ], "properties": { "amountIn": { "type": "string", "description": "Total required or quoted source input in source base units for the pooled trade." }, "estimatedAmountOut": { "type": "string", "description": "Gross pooled output in destination base units. For EXACT_OUTPUT this is the fixed combined destination target; participant outputs are allocated pro rata by confirmed source contributions, with the Leader fee deducted from follower shares." }, "minAmountOut": { "type": "string", "description": "Optional minimum destination amount, generally returned for EXACT_INPUT quotes." }, "quoteRequest": { "$ref": "#/components/schemas/OneClickQuoteRequest", "description": "Exact combined request sent to 1Click." }, "quoteResponse": { "$ref": "#/components/schemas/OneClickQuoteResponse", "description": "Full 1Click provider response. Live quotes can include deposit instructions; the response itself does not authorize a transfer." }, "minAmountIn": { "type": "string", "description": "Optional minimum accepted source amount, generally returned for EXACT_OUTPUT quotes." } }, "additionalProperties": false, "description": "Combined Leader and eligible-Follower projection. Amounts are estimates from the returned 1Click quote and do not guarantee final settlement." }, "expectedFee": { "$ref": "#/components/schemas/ExpectedFee", "description": "Estimated Leader fee withheld from eligible Followers’ output; it is rounded down to the destination asset’s smallest unit." }, "expiresAt": { "type": "string", "format": "date-time", "description": "Quote expiration. Balances and Followers are re-read when submitting the trade." }, "nextStep": { "type": "string", "description": "Mode-specific instruction for obtaining the final live quote and submitting the signed trade." }, "swapType": { "type": "string", "enum": [ "EXACT_INPUT", "EXACT_OUTPUT" ], "description": "Swap direction requested by the app." } }, "additionalProperties": true, "description": "Dry estimate for one pooled trade. In EXACT_OUTPUT mode combinedAmountOut is the fixed gross destination output; Hitch splits the required source input by available balances, then allocates the fixed output by actual confirmed contribution shares. The Leader fee is withheld from follower shares." }, "CurrentAccount": { "type": "object", "required": [ "verified", "sessionId", "accountId", "walletType", "walletAddress", "role", "verifiedAt", "expiresAt", "balancesAuthorized" ], "properties": { "verified": { "const": true }, "sessionId": { "type": "string" }, "accountId": { "type": "string" }, "walletType": { "$ref": "#/components/schemas/WalletType" }, "walletAddress": { "type": "string" }, "role": { "type": "string", "enum": [ "leader", "follower" ] }, "verifiedAt": { "type": "null", "description": "The current-session endpoint does not persist a verification timestamp." }, "expiresAt": { "type": "string", "format": "date-time" }, "balancesAuthorized": { "type": "boolean" } }, "additionalProperties": false }, "ServiceUnavailable": { "description": "A required provider or data service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "CopyTradeSubmitResult": { "type": "object", "required": [ "tradeId", "status" ], "properties": { "tradeId": { "type": "string" }, "status": { "type": "string" }, "executionMode": { "$ref": "#/components/schemas/ExecutionMode" }, "needsLeaderAuthorization": { "type": "boolean" }, "leaderIntent": { "oneOf": [ { "$ref": "#/components/schemas/SignedIntent" }, { "type": "null" } ] }, "message": { "type": "string" }, "statusUrl": { "type": "string" }, "intentHash": { "type": "string" } }, "additionalProperties": true }, "LeaderWriteResult": { "type": "object", "required": [ "registered", "leaderAccountId", "feeBps", "feeChangePending", "registeredAt", "leader" ], "properties": { "registered": { "type": "boolean" }, "leaderAccountId": { "type": "string" }, "feeBps": { "type": "integer" }, "feeChangePending": { "type": "boolean" }, "followersRequiringConfirmation": { "type": "integer" }, "copyTradingEnabledFollowerCount": { "type": "integer" }, "registeredAt": { "type": "string", "format": "date-time" }, "leader": { "type": "object", "required": [ "accountId", "createdAt", "copyTradingFeeBps", "copyTradingFeeVersion" ], "properties": { "accountId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "blockchain": { "type": [ "string", "null" ] }, "copyTradingFeeBps": { "type": "integer" }, "copyTradingFeeVersion": { "type": "integer" } }, "additionalProperties": true } }, "additionalProperties": true }, "FollowOperationPreparation": { "type": "object", "required": [ "operationId", "action", "leaderAccountId", "serverPublicKey", "payload", "copyTradingFeeBps", "status" ], "properties": { "operationId": { "type": "string", "format": "uuid" }, "action": { "type": "string", "enum": [ "FOLLOW", "UNFOLLOW" ] }, "leaderAccountId": { "type": "string" }, "serverPublicKey": { "type": "string" }, "payload": { "type": [ "string", "null" ], "description": "Exact serialized Intents authorization to sign; null if this operation has already been submitted." }, "copyTradingFeeBps": { "type": [ "integer", "null" ] }, "status": { "type": "string" }, "intentHash": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "FollowCurrent": { "type": "object", "required": [ "activeLeaderAccountId", "activeLeaderFeeConfirmed", "pendingOperation" ], "properties": { "activeLeaderAccountId": { "type": [ "string", "null" ] }, "activeLeaderFeeConfirmed": { "type": "boolean" }, "pendingOperation": { "oneOf": [ { "type": "object", "required": [ "operationId", "action", "leaderAccountId", "serverPublicKey", "payload", "copyTradingFeeBps", "status" ], "properties": { "operationId": { "type": "string", "format": "uuid" }, "action": { "type": "string", "enum": [ "FOLLOW", "UNFOLLOW" ] }, "leaderAccountId": { "type": "string" }, "serverPublicKey": { "type": "string" }, "payload": { "type": [ "string", "null" ], "description": "Exact serialized Intents authorization to sign; null if this operation has already been submitted." }, "copyTradingFeeBps": { "type": [ "integer", "null" ] }, "status": { "type": "string" }, "intentHash": { "type": [ "string", "null" ] } }, "additionalProperties": true }, { "type": "null" } ] } }, "additionalProperties": true }, "FollowFeeConfirmationResult": { "type": "object", "required": [ "confirmed", "leaderAccountId", "copyTradingFeeBps" ], "properties": { "confirmed": { "const": true }, "leaderAccountId": { "type": "string" }, "copyTradingFeeBps": { "type": "integer" } }, "additionalProperties": false }, "WalletRoleInput": { "type": "string", "enum": [ "leader", "follower", "LEADER", "FOLLOWER" ], "description": "Role the connected signer is verifying for." }, "CopyTradeCancelResult": { "type": "object", "required": [ "tradeId", "status" ], "properties": { "tradeId": { "type": "string", "description": "Hitch trade ID." }, "status": { "type": "string", "description": "Current cancellation or trade state." }, "actionRequired": { "type": [ "string", "null" ], "description": "Next cancellation reconciliation step, if any." } }, "additionalProperties": true } }, "responses": { "BadRequest": { "description": "Malformed request or invalid payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "INVALID_INPUT", "message": "amount must be a positive integer string in base units", "requestId": "req_example_01" } } } }, "Unauthorized": { "description": "Partner key or user session is absent, invalid, or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "SESSION_EXPIRED", "message": "Verify the wallet again to continue.", "requestId": "req_example_02" } } } }, "NotFound": { "description": "The resource does not exist or is not visible to this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "NOT_FOUND", "message": "The requested resource was not found.", "requestId": "req_example_03" } } } }, "Conflict": { "description": "The requested transition conflicts with current relationship or trade state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "ACTIVE_LEADER_EXISTS", "message": "This follower already has an active leader.", "requestId": "req_example_04" } } } }, "UnprocessableEntity": { "description": "A validly shaped request cannot be quoted or executed with current asset, balance, or provider constraints.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "INSUFFICIENT_BALANCE", "message": "The current account balance is below the requested input.", "requestId": "req_example_05" } } } }, "PreconditionRequired": { "description": "A required read-only balance authorization or active follower delegation is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "BALANCE_AUTHORIZATION_REQUIRED", "message": "Authorize read-only balance access before requesting a quote.", "requestId": "req_example_06" } } } }, "RateLimited": { "description": "Partner or account rate limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "Forbidden": { "description": "The authenticated partner is not allowed to use the requested origin, role, or account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": "FORBIDDEN", "message": "This operation is not enabled for this partner or account.", "requestId": "req_example_07" } } } }, "ServiceUnavailable": { "description": "A required provider or data service is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }