{ "openapi": "3.1.0", "info": { "title": "ArCa Client Integration API", "version": "1.0.0", "description": "Available first-party HTTP endpoints for fiat-to-USDT funding orders, USDT savings, token swaps, market discovery, and referral membership. These routes currently use ArCa Privy user sessions and linked-wallet checks; the document does not grant a partner API credential or replace wallet signatures. Funding orders are fulfilled through the implemented P2P provider flow. The API returns errors when providers, liquidity, or execution services are unavailable." }, "servers": [ { "url": "https://app.ar-ca.org", "description": "Production" }, { "url": "https://dev.app.ar-ca.org", "description": "Preview" } ], "paths": { "/api/funding/orders": { "get": { "operationId": "listFundingOrders", "summary": "List my funding orders", "tags": [ "Funding orders" ], "responses": { "200": { "description": "Current user orders", "content": { "application/json": { "schema": { "type": "object", "properties": { "orders": { "type": "array", "items": { "$ref": "#/components/schemas/FundingOrder" } } }, "required": [ "orders" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Wallet or account is not authorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Order or assignment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Order state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Service or provider unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "PrivyBearer": [] } ], "x-availability": "available" }, "post": { "operationId": "createFundingOrder", "summary": "Create a cash-in or cash-out order", "tags": [ "Funding orders" ], "responses": { "200": { "description": "Created order", "content": { "application/json": { "schema": { "type": "object", "properties": { "order": { "$ref": "#/components/schemas/FundingOrder" } }, "required": [ "order" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Wallet or account is not authorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Order or assignment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Order state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Service or provider unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FundingOrderRequest" } } } }, "security": [ { "PrivyBearer": [] } ], "description": "Creates an order from a live quoteId or direct order terms. For direct buy_usdt, fiatAmount and assetAmount are required; for direct sell_usdt, assetAmount is required. paymentMethod is always required. Provider assignment and fulfillment remain asynchronous.", "x-availability": "available" } }, "/api/funding/orders/{orderId}": { "get": { "operationId": "getFundingOrder", "summary": "Get a funding order", "tags": [ "Funding orders" ], "responses": { "200": { "description": "Current user order", "content": { "application/json": { "schema": { "type": "object", "properties": { "order": { "$ref": "#/components/schemas/FundingOrder" } }, "required": [ "order" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Wallet or account is not authorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Order or assignment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Order state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Service or provider unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "PrivyBearer": [] } ], "x-availability": "available" } }, "/api/funding/orders/{orderId}/payment-confirmed": { "post": { "operationId": "confirmFundingPayment", "summary": "Confirm user payment", "tags": [ "Funding orders" ], "responses": { "200": { "description": "Updated order", "content": { "application/json": { "schema": { "type": "object", "properties": { "order": { "$ref": "#/components/schemas/FundingOrder" } }, "required": [ "order" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Wallet or account is not authorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Order or assignment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Order state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Service or provider unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "proofFileId": { "type": "string" }, "paymentReference": { "type": "string" } }, "additionalProperties": false } } } }, "security": [ { "PrivyBearer": [] } ], "x-availability": "available" } }, "/api/funding/orders/{orderId}/proofs": { "post": { "operationId": "uploadUserOrderProof", "summary": "Upload a user payment proof", "tags": [ "Funding orders" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonObject" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Wallet or account is not authorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Order or assignment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Order state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Service or provider unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ProofUpload" } } } }, "security": [ { "PrivyBearer": [] } ], "x-availability": "available" } }, "/api/funding/orders/{orderId}/proofs/{proofId}": { "get": { "operationId": "getOrderProof", "summary": "Get authorized proof image bytes", "tags": [ "Funding orders" ], "responses": { "200": { "description": "Proof image", "content": { "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/webp": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Wallet or account is not authorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Order or assignment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Order state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Service or provider unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "proofId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "PrivyBearer": [] } ], "x-availability": "available" } }, "/api/funding/orders/{orderId}/release": { "post": { "operationId": "releaseFundingOrder", "summary": "Release a funding order", "tags": [ "Funding orders" ], "responses": { "200": { "description": "Updated order", "content": { "application/json": { "schema": { "type": "object", "properties": { "order": { "$ref": "#/components/schemas/FundingOrder" } }, "required": [ "order" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Wallet or account is not authorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Order or assignment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Order state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Service or provider unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "PrivyBearer": [] } ], "x-availability": "available" } }, "/api/funding/orders/quote": { "post": { "operationId": "quoteFundingOrder", "summary": "Quote a cash-in or cash-out order", "tags": [ "Funding orders" ], "responses": { "200": { "description": "Live P2P quote", "content": { "application/json": { "schema": { "type": "object", "properties": { "quote": { "$ref": "#/components/schemas/FundingQuote" } }, "required": [ "quote" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Wallet or account is not authorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Order or assignment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Order state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Service or provider unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FundingQuoteRequest" } } } }, "security": [ { "PrivyBearer": [] } ], "description": "Available P2P fiat-to-USDT or USDT-to-fiat quote. Provide fiatAmount, assetAmount, or both as positive numbers. A quote can expire or fail when no provider is available.", "x-availability": "available" } }, "/api/markets": { "get": { "operationId": "getMarkets", "summary": "Get the active market catalog", "tags": [ "Markets" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonObject" } } } }, "304": { "description": "Catalog has not changed." }, "503": { "description": "Catalog unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Returns the immutable active catalog envelope. Send If-None-Match to receive 304 when unchanged.", "security": [], "x-availability": "available" } }, "/api/referrals": { "get": { "operationId": "getReferralMembership", "summary": "Read active referral membership", "responses": { "200": { "description": "Active member", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "profile" ], "properties": { "profile": { "$ref": "#/components/schemas/ReferralProfile" } } } } } }, "401": { "description": "Invalid or missing Privy token", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "invite_required", "member_inactive", "recovery_unavailable" ] } } } } } }, "403": { "description": "invite_required or member_inactive", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "invite_required", "member_inactive", "recovery_unavailable" ] } } } } } }, "503": { "description": "Membership lookup unavailable", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "invite_required", "member_inactive", "recovery_unavailable" ] } } } } } } }, "security": [ { "PrivyBearer": [] } ], "tags": [ "Referrals" ], "x-availability": "available" } }, "/api/referrals/recover": { "post": { "operationId": "recoverReferralMembership", "summary": "Recover a historical funded Privy member", "description": "Uses only server-fetched Privy creation time and embedded wallets. Accounts must predate 2026-09-06T16:00:00Z. Supported raw positive token or Kamino deposit balances qualify. Existing active members need no balance recheck. Recovery admits under ARCA-Z23YA and records incoming legacy codes only as pending unverified metadata. Provider failures are retryable. Set REFERRAL_LEGACY_RECOVERY_ENABLED=0 to disable new admissions without disabling existing memberships.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "incomingReferralCode": { "type": "string", "pattern": "^ARCA-[A-HJ-NP-Z2-9]{5}$" } } } } } }, "responses": { "200": { "description": "Existing or recovered durable membership", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "profile" ], "properties": { "status": { "enum": [ "existing", "recovered" ] }, "profile": { "$ref": "#/components/schemas/ReferralProfile" } } } } } }, "400": { "description": "Malformed request", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "invite_required", "member_inactive", "recovery_unavailable" ] } } } } } }, "401": { "description": "Invalid or missing Privy token", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "invite_required", "member_inactive", "recovery_unavailable" ] } } } } } }, "403": { "description": "invite_required or member_inactive; accounts created at or after the recovery cutoff continue to ordinary invite admission even when legacy recovery is disabled", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "invite_required", "member_inactive", "recovery_unavailable" ] } } } } } }, "503": { "description": "Recovery disabled for a pre-cutoff account, or verification/database unavailable; retry without attempting ordinary invite admission", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "invite_required", "member_inactive", "recovery_unavailable" ] } } } } } } }, "tags": [ "Referrals" ], "x-availability": "available", "security": [ { "PrivyBearer": [] } ] } }, "/api/savings/deposit": { "post": { "operationId": "prepareSavingsDeposit", "summary": "Prepare a sponsored savings deposit", "tags": [ "Savings" ], "responses": { "200": { "description": "Transaction for user signing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavingsPreparedTransaction" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Wallet or account is not authorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "Upstream provider failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Service or provider unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SolanaOwnerAmount" } } } }, "security": [ { "PrivyBearer": [] } ], "x-availability": "available" } }, "/api/savings/position": { "get": { "operationId": "getSavingsPosition", "summary": "Get a Kamino USDT savings position", "tags": [ "Savings" ], "responses": { "200": { "description": "Current savings position and live supply APY", "content": { "application/json": { "schema": { "type": "object", "properties": { "position": { "$ref": "#/components/schemas/SavingsPosition" } }, "required": [ "position" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Wallet or account is not authorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "Upstream provider failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Service or provider unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "owner", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Wallet address." } ], "security": [ { "PrivyBearer": [] } ], "x-availability": "available" } }, "/api/savings/submit": { "post": { "operationId": "submitSavingsTransaction", "summary": "Submit a signed savings transaction", "tags": [ "Savings" ], "responses": { "200": { "description": "Submitted Solana transaction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavingsSubmittedTransaction" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Wallet or account is not authorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "Upstream provider failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Service or provider unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "enum": [ "deposit", "withdraw" ] }, "owner": { "type": "string" }, "signedTransaction": { "type": "string", "contentEncoding": "base64" } }, "required": [ "action", "owner", "signedTransaction" ], "additionalProperties": false } } } }, "security": [ { "PrivyBearer": [] } ], "x-availability": "available" } }, "/api/savings/withdraw": { "post": { "operationId": "prepareSavingsWithdraw", "summary": "Prepare a sponsored savings withdrawal", "tags": [ "Savings" ], "responses": { "200": { "description": "Transaction for user signing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavingsPreparedTransaction" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Wallet or account is not authorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "Upstream provider failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Service or provider unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavingsWithdrawRequest" } } } }, "security": [ { "PrivyBearer": [] } ], "description": "Prepare a USDT withdrawal. amount accepts a decimal string or the literal max for the full savings position.", "x-availability": "available" } }, "/api/swap": { "get": { "operationId": "getSwapQuote", "summary": "Get an aggregator swap quote", "tags": [ "Swap" ], "responses": { "200": { "description": "Available provider quote", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SwapQuote" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Smoke wallet mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Insufficient route liquidity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Provider rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Quote unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "chainId", "in": "query", "required": true, "schema": { "enum": [ "1", "56", "42161", "solana" ] } }, { "name": "sellToken", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "buyToken", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "sellAmount", "in": "query", "required": true, "schema": { "type": "string", "description": "Decimal amount expressed as text; never use a floating-point JSON number." } }, { "name": "taker", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "provider", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "positionExit", "in": "query", "required": false, "schema": { "enum": [ "0", "1" ] } }, { "name": "demo", "in": "query", "required": false, "schema": { "enum": [ "0", "1" ] } } ], "security": [], "description": "Quotes a supported token pair on one chain. Both tokens must resolve to configured assets or stablecoins. A quote can be indicative; execution requires an executable trade payload and current authorization. The route is not a general unrestricted asset-to-asset swap API.", "x-availability": "available" }, "post": { "operationId": "submitSwap", "summary": "Submit a signed aggregator swap", "tags": [ "Swap" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonObject" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Wallet or account is not authorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Service or provider unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "description": "Submits the provider-specific trade returned by a current executable quote, with wallet-signed authorization or transaction bytes as required. The server revalidates authorization, provider, chain, and trade semantics.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SwapSubmitRequest" } } } }, "security": [ { "PrivyBearer": [] } ], "x-availability": "available" } }, "/api/swap/balance": { "get": { "operationId": "getSwapBalance", "summary": "Get one token balance", "tags": [ "Swap" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonObject" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Wallet or account is not authorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "Upstream provider failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Service or provider unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "chainId", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "owner", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Wallet address." }, { "name": "token", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "assetKey", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "tokenAddress", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "pairToken", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "demo", "in": "query", "required": false, "schema": { "type": "string" } } ], "security": [], "description": "Read-only wallet balance lookup for a linked client flow. This route does not establish ownership or authorize execution.", "x-availability": "available" } }, "/api/swap/balances": { "get": { "operationId": "getSwapBalances", "summary": "Get Solana token balances", "tags": [ "Swap" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonObject" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Wallet or account is not authorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "Upstream provider failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Service or provider unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "chainId", "in": "query", "required": true, "schema": { "const": "solana" } }, { "name": "owner", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Wallet address." }, { "name": "tokens", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated symbols; mutually exclusive with assetKeys." }, { "name": "assetKeys", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated catalog keys; mutually exclusive with tokens." }, { "name": "pairToken", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "demo", "in": "query", "required": false, "schema": { "type": "string" } } ], "security": [], "description": "Read-only wallet balance lookup for a linked client flow. This route does not establish ownership or authorize execution.", "x-availability": "available" } } }, "components": { "securitySchemes": { "PrivyBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "schemas": { "ReferralProfile": { "type": "object", "required": [ "userId", "inviteCode", "stats", "recentInvites" ], "properties": { "userId": { "type": "string" }, "inviteCode": { "type": "string", "pattern": "^ARCA-[A-HJ-NP-Z2-9]{5}$" }, "stats": { "type": "object", "required": [ "firstDegreeInvites" ], "properties": { "firstDegreeInvites": { "type": "integer", "minimum": 0 } } }, "recentInvites": { "type": "array", "items": { "type": "object", "required": [ "id", "label", "joinedAt" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "joinedAt": { "type": "string" } } } }, "inviteUrl": { "type": "string", "format": "uri" }, "invitePath": { "type": "string" } } }, "ApiError": { "type": "object", "properties": { "error": { "type": "string" } }, "additionalProperties": false }, "JsonObject": { "type": "object", "additionalProperties": true, "description": "Provider and asset-specific fields are returned as an object; clients should ignore unknown fields." }, "SolanaOwnerAmount": { "type": "object", "properties": { "owner": { "type": "string" }, "amount": { "type": "string", "description": "Decimal amount expressed as text; never use a floating-point JSON number." } }, "required": [ "owner", "amount" ], "additionalProperties": false }, "FundingQuoteRequest": { "type": "object", "properties": { "direction": { "enum": [ "buy_usdt", "sell_usdt" ], "description": "buy_usdt is fiat cash-in; sell_usdt is fiat cash-out." }, "fiatAmount": { "type": "number", "exclusiveMinimum": 0, "description": "Positive amount in the indicated currency or asset." }, "assetAmount": { "type": "number", "exclusiveMinimum": 0, "description": "Positive amount in the indicated currency or asset." }, "paymentRail": { "enum": [ "wallet", "bank" ] }, "chain": { "enum": [ "ethereum", "tron", "solana" ] } }, "required": [ "direction", "paymentRail", "chain" ], "additionalProperties": false }, "FundingOrderRequest": { "type": "object", "properties": { "quoteId": { "type": "string", "description": "Use a live quote ID for quote-bound order creation. Alternatively provide direct order terms." }, "direction": { "enum": [ "buy_usdt", "sell_usdt" ] }, "fiatAmount": { "type": "number", "exclusiveMinimum": 0, "description": "Positive amount in the indicated currency or asset." }, "assetAmount": { "type": "number", "exclusiveMinimum": 0, "description": "Positive amount in the indicated currency or asset." }, "paymentRail": { "enum": [ "wallet", "bank" ] }, "chain": { "enum": [ "ethereum", "tron", "solana" ] }, "paymentMethod": { "$ref": "#/components/schemas/PaymentMethod" }, "recipientDetails": { "$ref": "#/components/schemas/RecipientDetails" }, "cashInRecipientWalletAddress": { "type": "string" } }, "required": [ "paymentMethod" ], "additionalProperties": false }, "ProofUpload": { "type": "object", "properties": { "image": { "type": "string", "format": "binary", "description": "JPEG, PNG, or WebP; maximum 5 MB." } }, "required": [ "image" ] }, "PaymentMethod": { "type": "object", "properties": { "railType": { "enum": [ "wallet", "bank" ] }, "providerName": { "type": "string" }, "accountName": { "type": "string" }, "maskedAccount": { "type": "string" }, "label": { "type": "string" } }, "required": [ "railType", "providerName", "accountName", "maskedAccount", "label" ], "additionalProperties": false }, "RecipientDetails": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "phone": { "type": "object", "properties": { "countryCode": { "type": "string" }, "number": { "type": "string" } }, "required": [ "countryCode", "number" ], "additionalProperties": false }, "address": { "type": "string" }, "bank": { "type": "object", "properties": { "branch": { "type": "string" }, "address": { "type": "string" }, "accountType": { "enum": [ "Checking", "Savings", "Current", null ] }, "accountNumber": { "type": "string" }, "swiftCode": { "type": "string" }, "accountHolderAddress": { "type": "string" } }, "required": [ "branch", "address", "accountType", "accountNumber", "swiftCode", "accountHolderAddress" ], "additionalProperties": false } }, "required": [ "email", "phone", "address" ], "additionalProperties": false }, "FundingQuote": { "type": "object", "properties": { "id": { "type": "string" }, "providerId": { "type": [ "string", "null" ] }, "direction": { "enum": [ "buy_usdt", "sell_usdt" ] }, "fiatAmount": { "type": "number", "exclusiveMinimum": 0, "description": "Positive amount in the indicated currency or asset." }, "assetAmount": { "type": "number", "exclusiveMinimum": 0, "description": "Positive amount in the indicated currency or asset." }, "paymentRail": { "enum": [ "wallet", "bank" ] }, "chain": { "enum": [ "ethereum", "tron", "solana" ] }, "lockedRate": { "type": [ "number", "null" ] }, "providerRankRate": { "type": [ "number", "null" ] }, "officialRate": { "type": [ "number", "null" ] }, "marginBps": { "type": [ "number", "null" ] }, "providerCostRate": { "type": [ "number", "null" ] }, "fxMarginProfit": { "type": [ "number", "null" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "providerId", "direction", "fiatAmount", "assetAmount", "paymentRail", "chain", "lockedRate", "providerRankRate", "expiresAt", "createdAt" ], "additionalProperties": false }, "FundingOrder": { "type": "object", "properties": { "id": { "type": "string" }, "orderNumber": { "type": "string" }, "status": { "enum": [ "quoted", "posted", "assigned", "accepted", "filling", "fulfilled", "failed", "expired" ] }, "quote": { "$ref": "#/components/schemas/FundingQuote" }, "paymentMethod": { "$ref": "#/components/schemas/PaymentMethod" }, "currentAssignment": { "type": [ "object", "null" ], "additionalProperties": true }, "assignedProvider": { "type": [ "object", "null" ], "additionalProperties": true }, "providerTransferDetails": { "type": "object", "additionalProperties": true }, "transfers": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "proofs": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "orderNumber", "status", "quote", "paymentMethod", "transfers", "proofs", "createdAt", "updatedAt" ], "additionalProperties": true }, "SavingsPosition": { "type": "object", "properties": { "protocol": { "type": "string" }, "market": { "type": "string" }, "reserve": { "type": "string" }, "owner": { "type": "string" }, "token": { "const": "USDT" }, "supplyApy": { "type": "number", "description": "Current Kamino supply APY as a decimal fraction." }, "savingsBalance": { "type": "string" }, "principalAmount": { "type": "string" }, "accruedAmount": { "type": "string" }, "historicalRealizedSavingsAmount": { "type": "string" }, "totalSavingsAmount": { "type": "string" }, "totalSavingsStatus": { "enum": [ "complete", "current-position-only", "unavailable" ] }, "fetchedAt": { "type": "string", "format": "date-time" }, "estimated": { "const": false } }, "required": [ "protocol", "market", "reserve", "owner", "token", "supplyApy", "savingsBalance", "principalAmount", "accruedAmount", "historicalRealizedSavingsAmount", "totalSavingsAmount", "totalSavingsStatus", "fetchedAt", "estimated" ], "additionalProperties": false }, "SavingsPreparedTransaction": { "type": "object", "properties": { "transaction": { "type": "string", "contentEncoding": "base64" }, "protocol": { "type": "string" }, "action": { "enum": [ "deposit", "withdraw" ] }, "requiresFeePayerSignature": { "type": "boolean" } }, "required": [ "transaction", "protocol", "action" ], "additionalProperties": false }, "SavingsWithdrawRequest": { "type": "object", "properties": { "owner": { "type": "string" }, "amount": { "anyOf": [ { "type": "string", "pattern": "^[0-9]+(?:\\.[0-9]+)?$" }, { "const": "max" } ] } }, "required": [ "owner", "amount" ], "additionalProperties": false }, "SavingsSubmittedTransaction": { "type": "object", "properties": { "success": { "const": true }, "protocol": { "type": "string" }, "action": { "enum": [ "deposit", "withdraw" ] }, "signature": { "type": "string" }, "tradeHash": { "type": "string" } }, "required": [ "success", "protocol", "action", "signature", "tradeHash" ], "additionalProperties": false }, "SwapQuote": { "type": "object", "properties": { "provider": { "enum": [ "cow", "1inch", "0x", "jupiter", "raydium_cpmm" ] }, "chainId": { "oneOf": [ { "type": "integer", "enum": [ 1, 56, 42161 ] }, { "const": "solana" } ] }, "sellToken": { "type": "string" }, "buyToken": { "type": "string" }, "sellAmount": { "type": "string" }, "buyAmount": { "type": "string" }, "quoteKind": { "enum": [ "indicative", "executable" ] }, "liquidityAvailable": { "type": "boolean" }, "liquidityStatus": { "enum": [ "available", "below_minimum", "zero", "unavailable" ] }, "trade": { "type": "object", "additionalProperties": true, "description": "Provider-specific execution payload, including authorization or unsigned transaction where applicable." }, "approval": { "type": "object", "additionalProperties": true }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "provider", "chainId", "sellToken", "buyToken", "sellAmount", "buyAmount", "liquidityAvailable" ], "additionalProperties": true }, "SwapSubmitRequest": { "type": "object", "properties": { "chainId": { "oneOf": [ { "type": "integer", "enum": [ 1, 56, 42161 ] }, { "type": "string", "enum": [ "1", "56", "42161", "solana" ] } ] }, "provider": { "enum": [ "cow", "1inch", "0x", "jupiter", "raydium_cpmm" ] }, "takerAddress": { "type": "string" }, "walletChainType": { "enum": [ "evm", "solana" ] }, "trade": { "type": "object", "additionalProperties": true }, "approval": { "type": "object", "additionalProperties": true }, "liquidityAcknowledged": { "type": "boolean" }, "demo": { "type": "boolean" } }, "required": [ "chainId", "provider", "takerAddress", "trade" ], "additionalProperties": true } } }, "tags": [ { "name": "Funding orders", "description": "Fiat cash-in and cash-out orders settled in USDT through the available P2P provider flow." }, { "name": "Savings", "description": "Kamino USDT savings position, live rate, and signed deposit or withdrawal flow." }, { "name": "Swap", "description": "Supported same-chain token swap quotes and submissions." }, { "name": "Markets", "description": "Active market catalog used to select supported assets." }, { "name": "Referrals", "description": "First-party invite membership and historical recovery." } ] }