Upload Cost: 0.001000 USDC on Base
\n \n \n \n \n\n" } } }, "400": { "description": "Bad Request", "content": { "text/plain": { "schema": { "type": "string", "example": "Invalid byte count" } } } }, "503": { "description": "Service Unavailable", "content": { "text/plain": { "schema": { "type": "string", "example": "Pricing oracle unavailable" } } } } } } }, "/x402/payment/{signatureType}/{address}": { "post": { "tags": [ "x402" ], "summary": "Verify and settle x402 payment", "description": "Verifies an EIP-3009 payment authorization and settles payment on-chain according to the specified mode.\n\n**This is Phase 2 of the x402 flow** - verifying and settling the payment.\n\n**Process:**\n1. Decode base64 payment header to extract EIP-3009 authorization\n2. Verify EIP-712 signature matches authorization parameters\n3. Check authorization hasn't been used or expired\n4. Call USDC contract's `receiveWithAuthorization()` to settle payment\n5. Convert USDC → Winston (Arweave storage credits)\n6. Apply payment according to mode (payg, topup, or hybrid)\n7. Record transaction in database with payment ID\n8. Return success with transaction hash for verification\n\n**Payment Modes:**\n- **payg** (Pay-as-you-go): Payment reserved for specific upload only\n- **topup**: Entire payment amount credited to user's account balance\n- **hybrid**: Reserve for upload + credit any excess to balance (DEFAULT)\n\n**Security:**\n- EIP-712 signature verification prevents unauthorized transfers\n- Nonce prevents replay attacks\n- validBefore/validAfter enforce time bounds\n- On-chain settlement provides cryptographic proof\n\n**Called by:** Upload service during data item upload when X-PAYMENT header is present\n", "parameters": [ { "name": "signatureType", "in": "path", "required": true, "schema": { "type": "integer", "description": "ANS-104 signature type (1=Arweave, 3=Ethereum, 4=Solana)", "enum": [ 1, 3, 4 ], "example": 3 } }, { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "description": "User's wallet address (used for tracking, not payment verification)", "example": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0" } } ], "requestBody": { "required": true, "description": "Payment authorization details extracted from X-PAYMENT header.\n\nThe upload service extracts this from the user's X-PAYMENT header and forwards it\nto the payment service for verification and settlement.\n", "content": { "application/json": { "schema": { "type": "object", "required": [ "paymentHeader", "byteCount" ], "properties": { "paymentHeader": { "type": "string", "format": "byte", "description": "Base64-encoded x402 payment authorization (same value from X-PAYMENT header).\n\n**Decodes to JSON with:**\n- x402Version: 1\n- scheme: \"exact\"\n- network: \"base-mainnet\" or \"base-sepolia\"\n- payload:\n - signature: EIP-712 signature of authorization\n - authorization:\n - from: Payer's Ethereum address\n - to: Recipient address (service's Ethereum wallet)\n - value: USDC amount in smallest unit (6 decimals)\n - validAfter: Unix timestamp\n - validBefore: Unix timestamp\n - nonce: Unique nonce (bytes32)\n", "example": "eyJ4NDAyVmVyc2lvbiI6MSwic2NoZW1lIjoiZXhhY3QiLCJuZXR3b3JrIjoiYmFzZS1tYWlubmV0IiwicGF5bG9hZCI6eyJzaWduYXR1cmUiOiIweGFiY2RlZi4uLiIsImF1dGhvcml6YXRpb24iOnsiZnJvbSI6IjB4NzQyZDM1Q2M2NjM0QzA1MzI5MjVhM2I4NDRCYzllNzU5NWYwYkViMCIsInRvIjoiMHg2QTBBMTBGZUQ4NWM5NzFCODQxYmVlODg5Mjg3OGMwZDU4M0JmNjciLCJ2YWx1ZSI6IjEwMDAwMDAiLCJ2YWxpZEFmdGVyIjowLCJ2YWxpZEJlZm9yZSI6MTczNTY4OTYwMCwibm9uY2UiOiIweDEyMzQ1Njc4OTBhYmNkZWYuLi4ifX19" }, "dataItemId": { "type": "string", "description": "Data item ID being uploaded (optional for PAYG mode).\n\nFor PAYG mode, this can be provided later via link endpoint.\nFor hybrid mode, this is required upfront.\n", "example": "QpmY8mZmFEC8RxNsgbxSV6e36OF6quIYaPRKzvUco0o" }, "byteCount": { "type": "integer", "minimum": 1, "description": "Declared byte count for the upload (required for PAYG and hybrid modes).\n\nUsed to calculate Winston cost and determine if payment is sufficient.\nMust match Content-Length header from upload request.\n", "example": 1024 }, "mode": { "type": "string", "description": "Payment mode - determines how payment is applied.\n\n**payg**: Payment reserved for this specific upload only\n**topup**: Entire payment credited to account balance\n**hybrid**: Reserve for upload + credit excess (DEFAULT)\n\nMost x402 clients use \"payg\" for stateless pay-per-upload.\n", "enum": [ "payg", "topup", "hybrid" ], "default": "hybrid", "example": "payg" } } }, "examples": { "PaygMode": { "summary": "Pay-as-you-go (most common for x402)", "value": { "paymentHeader": "eyJ4NDAyVmVyc2lvbiI6MSwic2NoZW1lIjoiZXhhY3QiLCJuZXR3b3JrIjoiYmFzZS1tYWlubmV0IiwicGF5bG9hZCI6ey4uLn19", "dataItemId": "QpmY8mZmFEC8RxNsgbxSV6e36OF6quIYaPRKzvUco0o", "byteCount": 1024, "mode": "payg" } }, "HybridMode": { "summary": "Hybrid (reserve + credit excess)", "value": { "paymentHeader": "eyJ4NDAyVmVyc2lvbiI6MSwic2NoZW1lIjoiZXhhY3QiLCJuZXR3b3JrIjoiYmFzZS1tYWlubmV0IiwicGF5bG9hZCI6ey4uLn19", "dataItemId": "QpmY8mZmFEC8RxNsgbxSV6e36OF6quIYaPRKzvUco0o", "byteCount": 1024, "mode": "hybrid" } } } } } }, "responses": { "200": { "description": "Payment verified and settled successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402PaymentResult" } } } }, "400": { "description": "Bad Request", "content": { "text/plain": { "schema": { "type": "string", "example": "Invalid payment header" } } } }, "402": { "description": "Payment verification failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402PaymentResult" } } } }, "503": { "description": "Service Unavailable", "content": { "text/plain": { "schema": { "type": "string", "example": "Payment service unavailable" } } } } } } }, "/x402/finalize": { "post": { "tags": [ "x402" ], "summary": "Finalize x402 payment after upload", "description": "Finalizes an x402 payment after upload completes by comparing declared vs actual byte count.\n\n**This is Phase 3 of the x402 flow** - fraud detection and finalization.\n\n**Called by:** Upload service after data item is fully received and validated.\n\n**Process:**\n1. Retrieve payment record by data item ID\n2. Compare actualByteCount vs declaredByteCount (from X-PAYMENT)\n3. Apply fraud tolerance threshold (default 5%)\n4. Determine status: confirmed, refunded, or fraud_penalty\n5. Issue refund if overpaid (actual < declared)\n6. Keep payment as penalty if underpaid (actual > declared + tolerance)\n7. Update payment record with final status\n\n**Fraud Detection:**\n- **Within tolerance**: Payment confirmed, upload proceeds\n- **Overpayment** (actual < declared - 5%): Refund difference to user\n- **Fraud** (actual > declared + 5%): Keep payment as penalty, reject upload\n\n**Why this matters:**\nUsers must provide Content-Length header accurately. If they lie about upload size\nto pay less, the system detects this and penalizes them by keeping the payment.\n\n**Security:** Prevents users from declaring small uploads but uploading large data.\n", "requestBody": { "required": true, "description": "Actual upload details after data item has been fully received", "content": { "application/json": { "schema": { "type": "object", "required": [ "dataItemId", "actualByteCount" ], "properties": { "dataItemId": { "type": "string", "description": "Data item ID that was uploaded (links to payment record)", "example": "QpmY8mZmFEC8RxNsgbxSV6e36OF6quIYaPRKzvUco0o" }, "actualByteCount": { "type": "integer", "minimum": 1, "description": "Actual byte count after upload completed and data item validated.\n\nThis is the true size of the ANS-104 data item (headers + payload).\nCompared against declaredByteCount from payment verification phase.\n", "example": 1024 } } }, "examples": { "MatchingSize": { "summary": "Actual matches declared (within tolerance)", "value": { "dataItemId": "QpmY8mZmFEC8RxNsgbxSV6e36OF6quIYaPRKzvUco0o", "actualByteCount": 1024 } }, "Overpayment": { "summary": "Actual less than declared (refund issued)", "value": { "dataItemId": "QpmY8mZmFEC8RxNsgbxSV6e36OF6quIYaPRKzvUco0o", "actualByteCount": 900 } }, "FraudAttempt": { "summary": "Actual exceeds declared (fraud penalty)", "value": { "dataItemId": "QpmY8mZmFEC8RxNsgbxSV6e36OF6quIYaPRKzvUco0o", "actualByteCount": 1200 } } } } } }, "responses": { "200": { "description": "Payment finalized successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402FinalizeResult" } } } }, "404": { "description": "Payment not found", "content": { "text/plain": { "schema": { "type": "string", "example": "Payment not found for data item" } } } }, "503": { "description": "Service Unavailable", "content": { "text/plain": { "schema": { "type": "string", "example": "Payment service unavailable" } } } } } } }, "/x402/top-up/{signatureType}/{address}": { "post": { "tags": [ "x402" ], "summary": "Top up credits using x402 payment", "description": "Top up your account balance by purchasing storage credits with USDC via x402.\n\n**This is a pure x402 flow** - the resource being purchased is \"storage credits.\"\n\n**Flow:**\n1. **First request (no X-PAYMENT header):** Returns 402 Payment Required with payment requirements\n2. **Retry with X-PAYMENT header:** Verifies payment, settles USDC, credits balance\n\n**Key Differences from Upload Payment:**\n- No data item involved - just purchasing credits\n- Supports multiple signature types (Arweave, Ethereum, Solana)\n- Entire payment amount converted to credits and added to balance\n- Can be used for any future uploads\n\n**Use Case:** AI agents or users who want to prepay for storage using USDC\n\n**Note:** While x402 currently only supports EVM chains (Base, Ethereum, Polygon),\nthis endpoint accepts signatureType for forward compatibility with future payment methods.\n", "parameters": [ { "name": "signatureType", "in": "path", "required": true, "schema": { "type": "integer", "enum": [ 1, 3, 4 ], "description": "ANS-104 signature type:\n- 1: Arweave (RSA-PSS)\n- 3: Ethereum (ECDSA secp256k1)\n- 4: Solana (EdDSA ed25519)\n\nCurrently, x402 only supports signatureType 3 (Ethereum), but this parameter\nis included for forward compatibility.\n", "example": 3 } }, { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "description": "User address that will receive the credits. Format depends on signatureType:\n- signatureType 1: Base64URL Arweave address\n- signatureType 3: 0x-prefixed Ethereum address (current x402 support)\n- signatureType 4: Base58 Solana address\n", "example": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0" } } ], "requestBody": { "required": true, "description": "Request body for top-up. On first request (without X-PAYMENT), this tells the service\nhow many bytes worth of credits you want to purchase.\n", "content": { "application/json": { "schema": { "type": "object", "required": [ "bytes" ], "properties": { "bytes": { "type": "integer", "minimum": 1, "description": "Number of bytes worth of storage credits to purchase.\n\nThis determines the USDC price. For example:\n- 1 GB (1,000,000,000 bytes) might cost ~$0.005 USDC\n- 10 GB (10,000,000,000 bytes) might cost ~$0.05 USDC\n\nThe service calculates: bytes → Winston → USD → USDC\n", "example": 10000000000 } } }, "examples": { "SmallTopUp": { "summary": "Top up for 1 GB", "value": { "bytes": 1000000000 } }, "LargeTopUp": { "summary": "Top up for 100 GB", "value": { "bytes": 100000000000 } } } } } }, "responses": { "200": { "description": "OK - Payment verified, settled, and credits added to balance.\n\nThe entire USDC payment has been converted to Winston credits and\ncredited to the user's account balance.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the top-up succeeded", "example": true }, "creditsGranted": { "type": "string", "description": "Amount of Winston credits granted (added to balance)", "example": "10000000000" }, "balance": { "type": "string", "description": "New total account balance in Winston", "example": "15000000000" }, "txHash": { "type": "string", "description": "Blockchain transaction hash for USDC payment", "example": "0xb8a52725cdc816d060392dcecaa1528872acf9ea0bd097a86e2432dd5d2213ca" }, "paymentId": { "type": "string", "format": "uuid", "description": "Unique payment ID for this transaction", "example": "550e8400-e29b-41d4-a716-446655440000" }, "network": { "type": "string", "description": "Network where payment was made", "example": "base-mainnet" } } }, "examples": { "Successful": { "summary": "Successfully topped up 10 GB", "value": { "success": true, "creditsGranted": "10000000000", "balance": "15000000000", "txHash": "0xb8a52725cdc816d060392dcecaa1528872acf9ea0bd097a86e2432dd5d2213ca", "paymentId": "550e8400-e29b-41d4-a716-446655440000", "network": "base-mainnet" } } } } } }, "400": { "description": "Bad Request", "content": { "text/plain": { "schema": { "type": "string", "example": "Invalid bytes parameter" } } } }, "402": { "description": "Payment Required - No X-PAYMENT header provided, or payment verification failed.\n\nClient should:\n1. Parse payment requirements from response\n2. Create EIP-3009 payment authorization\n3. Sign with EIP-712\n4. Retry request with X-PAYMENT header\n", "headers": { "X-Payment-Required": { "schema": { "type": "string", "example": "x402-1" }, "description": "Indicates x402 protocol version 1 is supported" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402PaymentRequiredResponse" }, "examples": { "SingleNetwork": { "summary": "Payment required for 10 GB topup", "value": { "x402Version": 1, "accepts": [ { "scheme": "exact", "network": "base-mainnet", "maxAmountRequired": "50000", "resource": "/v1/x402/top-up/3/0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0", "description": "Top up storage credits for 10000000000 bytes", "mimeType": "application/json", "outputSchema": { "type": "object", "properties": { "success": { "type": "boolean" }, "creditsGranted": { "type": "string", "description": "Winston credits granted" }, "balance": { "type": "string", "description": "New total balance" }, "txHash": { "type": "string", "description": "Blockchain transaction hash" }, "paymentId": { "type": "string", "description": "Payment ID (UUID)" } } }, "payTo": "0x6A0A10FFD285c971B841bee8892878c0d583Bf67", "maxTimeoutSeconds": 300, "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "extra": { "name": "USD Coin", "version": "2" } } ] } } } } } }, "503": { "description": "Service Unavailable", "content": { "text/plain": { "schema": { "type": "string", "example": "x402 payments are not currently available" } } } } } } }, "/info": { "get": { "tags": [ "Info" ], "summary": "Get service information", "description": "Get the current version of the service and the addresses for the supported blockchains", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "string", "example": "0.2.0" }, "addresses": { "type": "object", "description": "Payment recipient addresses per token. Only tokens configured on\nthe service are present. `ed25519` aliases `solana`, and `pol`\naliases `matic`.\n", "properties": { "arweave": { "type": "string", "example": "JNC6vBhjHY1EPwV3pEeNmrsgFMxH5d38_LHsZ7jful8" }, "ethereum": { "type": "string", "example": 6.053775100077233e+47 }, "solana": { "type": "string", "example": "HepiT2k93CFQaSB7i3ZNXhybZKn5MeWiv3UkLsaJKk4i" }, "ed25519": { "type": "string", "description": "Alias for the Solana address.", "example": "HepiT2k93CFQaSB7i3ZNXhybZKn5MeWiv3UkLsaJKk4i" }, "ario": { "type": "string", "description": "ARIO SPL-token payment recipient (defaults to the Solana address unless ARIO_ADDRESS is set).", "example": "HepiT2k93CFQaSB7i3ZNXhybZKn5MeWiv3UkLsaJKk4i" }, "matic": { "type": "string", "example": 6.053775100077233e+47 }, "pol": { "type": "string", "description": "Alias for the Matic (Polygon) address.", "example": 6.053775100077233e+47 }, "base-eth": { "type": "string", "example": 6.053775100077233e+47 }, "usdc": { "type": "string", "description": "ERC-20 USDC on Ethereum. Present when ETHEREUM_ADDRESS is configured — an ERC-20 balance sits at the SAME EOA as `ethereum`, so this is that address, not a separate wallet.", "example": 6.053775100077233e+47 }, "base-usdc": { "type": "string", "description": "ERC-20 USDC on Base. Present when BASE_ETH_ADDRESS is configured — same EOA as `base-eth`.", "example": 6.053775100077233e+47 }, "kyve": { "type": "string", "example": "kyve1clmuh5sjw73784lg0gnf4p07qefzrtk78an698" } }, "example": { "arweave": "JNC6vBhjHY1EPwV3pEeNmrsgFMxH5d38_LHsZ7jful8", "ethereum": 6.053775100077233e+47, "solana": "HepiT2k93CFQaSB7i3ZNXhybZKn5MeWiv3UkLsaJKk4i", "ed25519": "HepiT2k93CFQaSB7i3ZNXhybZKn5MeWiv3UkLsaJKk4i", "ario": "HepiT2k93CFQaSB7i3ZNXhybZKn5MeWiv3UkLsaJKk4i", "matic": 6.053775100077233e+47, "pol": 6.053775100077233e+47, "base-eth": 6.053775100077233e+47, "usdc": 6.053775100077233e+47, "base-usdc": 6.053775100077233e+47, "kyve": "kyve1clmuh5sjw73784lg0gnf4p07qefzrtk78an698" } }, "gateway": { "type": "string", "description": "The primary gateway (first entry of gateways).", "example": "https://arweave.net/" }, "gateways": { "type": "array", "description": "All public-facing gateway URLs advertised by the service.", "items": { "type": "string" }, "example": [ "https://arweave.net/" ] } } } } } } } } }, "/arns/price/{intent}/{name}": { "get": { "tags": [ "ArNS" ], "summary": "Get price for ArNS name registration or operation", "description": "Returns the mARIO (AR.IO token) and Winston credit cost for an ArNS name operation.\n\nOptionally includes a fiat currency estimate if the `currency` query parameter is provided.\n\n**Supported Intents:**\n- **buy-record**: Purchase a new ArNS name\n- **upgrade-name**: Upgrade a lease to permabuy\n- **extend-lease**: Extend the lease duration\n- **increase-undername-limit**: Increase the number of permitted undernames\n", "parameters": [ { "name": "x-signature", "in": "header", "required": false, "schema": { "$ref": "#/components/schemas/SignatureHeader" } }, { "name": "x-nonce", "in": "header", "required": false, "schema": { "$ref": "#/components/schemas/NonceHeader" } }, { "name": "x-public-key", "in": "header", "required": false, "schema": { "$ref": "#/components/schemas/PublicKeyHeader" } }, { "name": "intent", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ArNSIntent" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string", "description": "The ArNS name (without .ar suffix)", "example": "myname" } }, { "name": "currency", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/CurrencyType" }, "description": "If provided, includes a fiat currency estimate in the response" }, { "name": "years", "in": "query", "required": false, "schema": { "type": "integer", "description": "Number of years for lease (required for buy-record and extend-lease)", "example": 1 } }, { "name": "type", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ArNSNameType" }, "description": "Type of name registration (required for buy-record)" }, { "name": "increaseQty", "in": "query", "required": false, "schema": { "type": "integer", "description": "Quantity to increase (required for increase-undername-limit)" } }, { "name": "processId", "in": "query", "required": false, "schema": { "type": "string", "description": "AR.IO process ID (optional)" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "mARIO": { "type": "string", "description": "mARIO token cost", "example": "1000000" }, "winc": { "type": "string", "description": "Winston credit cost of the NAME ONLY. For a buy-name this EXCLUDES the ANT spawn surcharge — quote wincTotalWithAntSpawn instead, or you will under-quote the purchase.", "example": "974711979594" }, "antSpawnSurchargeWinc": { "type": "string", "description": "Flat cost-recovery surcharge for the Solana rent Turbo fronts when minting the customer's ANT. Present only for intents that mint one (buy-name/buy-record). Config-driven and, with ARNS_RENT_SURCHARGE_ENABLED, derived per-request from live SOL/AR rates — never hardcode it.", "example": "600000000000" }, "wincTotalWithAntSpawn": { "type": "string", "description": "winc + antSpawnSurchargeWinc. THIS is the figure to charge or display for a purchase. Present only when a surcharge applies.", "example": "1474711979594" }, "fiatEstimate": { "type": "object", "description": "Fiat estimate (only if currency parameter provided)", "properties": { "paymentAmount": { "type": "integer", "description": "BASE payment amount in the smallest currency unit — excludes the ANT spawn surcharge. Use paymentAmountWithAntSpawn for the total." }, "paymentAmountWithAntSpawn": { "type": "integer", "description": "Total payment amount including the ANT spawn surcharge. Present only when a surcharge applies." }, "antSpawnSurchargeAmount": { "type": "integer", "description": "The surcharge alone, in the smallest currency unit." }, "quotedPaymentAmount": { "type": "integer", "description": "Quoted amount before adjustments" }, "excessWincAmount": { "type": "string", "description": "Excess winc if payment exceeds minimum" }, "adjustments": { "$ref": "#/components/schemas/Adjustment" }, "fees": { "$ref": "#/components/schemas/Adjustment" } } } } } } } }, "400": { "description": "Bad Request", "content": { "text/plain": { "schema": { "type": "string", "example": "Invalid ArNS name" } } } }, "503": { "description": "Service Unavailable", "content": { "text/plain": { "schema": { "type": "string", "example": "Price Oracle Unavailable" } } } } } } }, "/arns/purchase/{nonce}": { "get": { "tags": [ "ArNS" ], "summary": "Get ArNS purchase status", "description": "Retrieves the status of an ArNS purchase transaction by its nonce (unique ID).\n\nUse this endpoint to track the progress of a purchase initiated via POST /arns/purchase.\n", "parameters": [ { "name": "nonce", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The unique nonce returned when the purchase was initiated" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArNSPurchaseReceipt" } } } }, "400": { "description": "Bad Request", "content": { "text/plain": { "schema": { "type": "string", "example": "Purchase status not found" } } } }, "503": { "description": "Service Unavailable", "content": { "text/plain": { "schema": { "type": "string", "example": "Database unavailable" } } } } } } }, "/arns/quote/{method}/{address}/{currency}/{intent}/{name}": { "get": { "tags": [ "ArNS" ], "summary": "Get Stripe payment quote for ArNS name purchase", "description": "Creates a Stripe payment session (checkout or payment intent) for purchasing an ArNS name with fiat currency.\n\nThis endpoint:\n1. Calculates the mARIO and Winston credit cost\n2. Converts to the requested fiat currency\n3. Creates a Stripe payment session\n4. Stores a quote in the database\n5. Returns both the quote and payment session\n\n**Payment Methods:**\n- **checkout-session**: Full Stripe Checkout experience (redirects to Stripe)\n- **payment-intent**: Embedded payment flow (integrate in your UI)\n", "parameters": [ { "name": "x-signature", "in": "header", "required": false, "schema": { "$ref": "#/components/schemas/SignatureHeader" } }, { "name": "x-nonce", "in": "header", "required": false, "schema": { "$ref": "#/components/schemas/NonceHeader" } }, { "name": "x-public-key", "in": "header", "required": false, "schema": { "$ref": "#/components/schemas/PublicKeyHeader" } }, { "name": "method", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "checkout-session", "payment-intent" ], "description": "Stripe payment method type" } }, { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "description": "Destination Arweave address" } }, { "name": "currency", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/CurrencyType" } }, { "name": "intent", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ArNSIntent" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string", "description": "The ArNS name (without .ar suffix)" } }, { "name": "promoCode", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/PromoCode" } }, { "name": "uiMode", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/UiMode" } }, { "name": "returnUrl", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ReturnUrl" } }, { "name": "successUrl", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/SuccessUrl" } }, { "name": "cancelUrl", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/CancelUrl" } }, { "name": "years", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "type", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ArNSNameType" } }, { "name": "increaseQty", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "processId", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "purchaseQuote": { "$ref": "#/components/schemas/ArNSPurchaseQuote" }, "paymentSession": { "$ref": "#/components/schemas/PaymentSession" }, "adjustments": { "$ref": "#/components/schemas/Adjustment" }, "fees": { "$ref": "#/components/schemas/Adjustment" } } } } } }, "400": { "description": "Bad Request", "content": { "text/plain": { "schema": { "type": "string", "example": "Invalid parameters" } } } }, "503": { "description": "Service Unavailable", "content": { "text/plain": { "schema": { "type": "string", "example": "Stripe unavailable" } } } } } } }, "/arns/my-names/{address}": { "get": { "tags": [ "ArNS" ], "summary": "List the ArNS names a wallet bought through Turbo", "description": "Receipt history for a wallet — NOT an ownership oracle. A name that was\ntransferred away keeps its receipt and still appears here, so read\npresent control from the chain using the returned `antId`.\n\nOpen-by-address (no signature), mirroring `/account/balance`.\n", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "string", "description": "The wallet's Turbo identity (native address)." } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "names": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "antId": { "type": "string" }, "intent": { "type": "string" }, "type": { "type": "string", "enum": [ "lease", "permabuy" ] }, "years": { "type": "integer" }, "purchaseDate": { "type": "string", "format": "date-time" }, "custodial": { "type": "boolean", "description": "ALWAYS false. Turbo takes custody of no ANT, so\nthere is nothing for this to be true about. Retained\nfor wire compatibility; do not branch on it.\n" }, "selfCustody": { "type": "boolean" } } } } } } } } } } } }, "/arns/actions/{action}": { "post": { "tags": [ "ArNS" ], "summary": "Create an ArNS action", "description": "Creates and (where Turbo holds the authority) immediately performs an\nArNS action. Debits credits once, at creation, for ALL twelve actions —\nno action is free. The four ARIO-spending actions (`buy-name`,\n`extend-lease`, `upgrade-name`, `increase-undername-limit`) recover\ntheir registration cost; the other eight recover a small margin\nagainst Turbo's sponsored gas/rent.\n\n**Authorization:** payer signature always (x-signature / x-public-key /\nx-nonce). The five RECORD-SCOPED actions — `set-record`,\n`remove-record`, `set-record-metadata`, `remove-record-metadata` and\n`transfer-record` — additionally require the ANT owner's action-bound\nproof in the `x-owner-*` headers, verified against the ANT's CURRENT\nON-CHAIN owner. The proof binds every field it carries, so a signature\nauthorizing one set of metadata values does not authorize another.\n\n`set-record-metadata` fields are tri-state: omit one to leave it\nunchanged, or send `null` to clear it. Those are bound distinctly, so\n\"clear the description\" and \"set it to empty\" are different messages.\n\nThe returned `transaction` carries a Solana blockhash that dies in\n~60-90 seconds. Sign those exact bytes — never rebuild the message, or\nTurbo's fee-payer signature stops covering it.\n", "parameters": [ { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "buy-name", "extend-lease", "upgrade-name", "increase-undername-limit", "set-record", "remove-record", "add-controller", "remove-controller", "transfer", "set-record-metadata", "remove-record-metadata", "transfer-record" ] } }, { "name": "x-signature", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/SignatureHeader" } }, { "name": "x-public-key", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/PublicKeyHeader" } }, { "name": "x-nonce", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/NonceHeader" } }, { "name": "x-owner-signature", "in": "header", "required": false, "schema": { "type": "string", "description": "The five RECORD-SCOPED actions only — `set-record`,\n`remove-record`, `set-record-metadata`, `remove-record-metadata`\nand `transfer-record`. Ed25519 signature by the ANT's Solana key\nover `[\"arns\", action, ...fields].join(\"\\n\")` + the x-owner-nonce.\nVerified against the ANT's CURRENT on-chain owner.\n" } }, { "name": "x-owner-public-key", "in": "header", "required": false, "schema": { "type": "string" } }, { "name": "x-owner-nonce", "in": "header", "required": false, "schema": { "type": "string" } }, { "name": "x-owner-signature-type", "in": "header", "required": false, "schema": { "type": "integer", "example": 4, "description": "Signature type of the owner key (4 = Solana)." } }, { "name": "name", "in": "query", "required": false, "schema": { "type": "string" }, "description": "ArNS name. Required for buy-name / extend-lease / upgrade-name / increase-undername-limit." }, { "name": "ownerAddress", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The SOLANA address that owns (or will own) the ANT. NOT the wallet\nthat signed the request. Required for every ANT-scoped action.\n" }, { "name": "antId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Existing ANT. Required for every action except the four name actions." }, { "name": "target", "in": "query", "required": false, "schema": { "type": "string" }, "description": "transfer destination, or the controller for add/remove-controller (defaults to Turbo)." }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "lease", "permabuy" ] } }, { "name": "years", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 5 } }, { "name": "increaseQty", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "undername", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 61 } }, { "name": "transactionId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "ttlSeconds", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 60, "maximum": 86400 } }, { "name": "displayName", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "set-record-metadata. Tri-state — omit to leave unchanged, send\n`null` (JSON body) to CLEAR, or a value to set.\n" }, { "name": "recordLogo", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "set-record-metadata. Tri-state, as displayName." }, { "name": "recordDescription", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "set-record-metadata. Tri-state, as displayName." }, { "name": "recordKeywords", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "set-record-metadata. Comma-separated in a query string, or a JSON\narray in a body. Tri-state, as displayName.\n" }, { "name": "paidBy", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated addresses to charge instead of the signer, via a\ndelegated-payment approval they granted. Accepted in the query\nstring OR the JSON body — the turbo-sdk posts a bare path and puts\nevery param, this one included, in the body.\n" } ], "requestBody": { "required": false, "description": "Every parameter above may be sent as a JSON body instead of a query\nstring; the body wins where both are present. `antState` is\nbody-shaped and is the reason to prefer one — in a query string it\nmust be a JSON-encoded string.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "antState": { "$ref": "#/components/schemas/ArNSBuyAntState" }, "paidBy": { "type": "string", "description": "As the query parameter of the same name. Also accepted as a\nJSON array.\n" } } } } } }, "responses": { "200": { "description": "OK — inspect `status` to decide whether a signature is needed.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ArNSActionCompleted" }, { "$ref": "#/components/schemas/ArNSActionAwaitingSignature" } ] } } } }, "400": { "description": "Client error — unknown action, missing/invalid parameter, the gate is\noff, or the CHAIN rejected the instruction (the body names the Anchor\nerror). None of these succeed on retry.\n" }, "401": { "description": "Missing or invalid signature, or the owner proof is not from the ANT's current on-chain owner." }, "402": { "description": "Insufficient credits." }, "503": { "description": "Genuinely transient — retry is reasonable." } } } }, "/arns/actions/{action}/price": { "get": { "tags": [ "ArNS" ], "summary": "Price an ArNS action before creating it", "description": "Preview the winc a `POST /arns/actions/{action}` call for this SAME\naction will debit, without creating (or being charged for) one.\nCovers only the eight non-purchase actions (`set-record`,\n`remove-record`, `set-record-metadata`, `remove-record-metadata`,\n`transfer-record`, `add-controller`, `remove-controller`,\n`transfer`) — the four ARIO-purchase actions (`buy-name`,\n`extend-lease`, `upgrade-name`, `increase-undername-limit`) are\npriced by `GET /arns/price/{intent}/{name}` instead, since their\nprice depends on `name`/`type`/`years`/`increaseQty`, which this\nroute never asks for.\n\nBoth routes read the SAME pricing resolver the actual debit uses, so\na quote here cannot drift from what create actually charges.\n\n**No signature required.** The amount has no user-specific\ncomponent — it depends only on the action and live SOL/AR rates,\nnot on who is asking. Same 404-avoiding, \"a read costs nothing\"\nreasoning as `GET /arns/purchase/{nonce}`.\n", "parameters": [ { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "set-record", "remove-record", "set-record-metadata", "remove-record-metadata", "transfer-record", "add-controller", "remove-controller", "transfer" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string" }, "wincQty": { "type": "string", "description": "What POST /arns/actions/{action} will debit for this action right now." } } } } } }, "400": { "description": "Unknown action, one of the four ARIO-purchase actions (priced\nelsewhere — the body names the correct route), or the ArNS\nactions gate is off.\n" }, "503": { "description": "Genuinely transient (rate oracle unavailable) — retry is reasonable." } } } }, "/arns/actions/{nonce}/sign": { "post": { "tags": [ "ArNS" ], "summary": "Submit the owner-signed transaction for an action", "description": "One submit path for every action. Takes the base64 transaction returned\nby the create call, now carrying the ANT owner's signature.\n\n**No payer auth.** The authorization is the owner's signature inside the\ntransaction, which the chain enforces against those exact instructions;\nthe nonce is a random UUID capability. Requiring a second off-chain\nsignature would break flows where the signer is not the payer.\n\n**Idempotent.** A replay of a completed action returns its envelope with\n`alreadyCompleted: true` and performs no second purchase.\n", "parameters": [ { "name": "nonce", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "transaction" ], "properties": { "transaction": { "type": "string", "description": "Base64 wire transaction from the create call, signed by the ANT owner." } } } } } }, "responses": { "200": { "description": "OK — the action completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArNSActionCompleted" } } } }, "400": { "description": "Unknown nonce, missing/malformed transaction bytes, the action has\nEXPIRED (its blockhash is dead — credits are refunded automatically),\nor the chain rejected the instruction.\n" }, "503": { "description": "Transient — the chain was unreadable, so nothing was submitted." } } } }, "/arns/actions/{nonce}": { "get": { "tags": [ "ArNS" ], "summary": "ArNS action status", "description": "Open by nonce (a random UUID handed only to the caller who created the\naction). Deliberately does NOT echo the transaction bytes.\n", "parameters": [ { "name": "nonce", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "nonce": { "type": "string" }, "action": { "type": "string" }, "status": { "type": "string", "enum": [ "awaiting-signature", "completed", "expired" ] }, "antId": { "type": "string" }, "name": { "type": "string" }, "ownerAddress": { "type": "string", "description": "The SOLANA key that owns the ANT." }, "paidBy": { "type": "string", "description": "The TURBO identity that was debited. Never merged with ownerAddress." }, "messageId": { "type": "string" }, "wincQty": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "createdDate": { "type": "string", "format": "date-time" } } } } } }, "404": { "description": "No action found for that nonce." } } } }, "/reserve-balance/{token}/{signerAddress}": { "get": { "tags": [ "Protected" ], "summary": "Reserve user balance for data upload", "description": "**PROTECTED ROUTE** - Requires `PRIVATE_ROUTE_SECRET` authentication header.\n\nReserves Winston credits from a user's balance for an upcoming data upload.\nCalled by the upload service before accepting a data item upload.\n\nThe reservation is temporary and will be:\n- Finalized (deducted) when upload completes successfully\n- Refunded if upload fails or is canceled\n\n**Authorization:** `x-auth-token` header must match `PRIVATE_ROUTE_SECRET` environment variable.\n", "parameters": [ { "name": "x-auth-token", "in": "header", "required": true, "schema": { "type": "string", "description": "Must match PRIVATE_ROUTE_SECRET" } }, { "name": "token", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TokenType" }, "description": "Currently unused (kept for backward compatibility)" }, { "name": "signerAddress", "in": "path", "required": true, "schema": { "type": "string", "description": "User's wallet address" } }, { "name": "byteCount", "in": "query", "required": true, "schema": { "type": "integer", "description": "Number of bytes being uploaded" } }, { "name": "dataItemId", "in": "query", "required": true, "schema": { "type": "string", "description": "Data item ID for the upload" } }, { "name": "paidBy", "in": "query", "required": false, "schema": { "type": "string", "description": "Comma-separated list of addresses paying (delegated payment)" } }, { "name": "paymentDirective", "in": "query", "required": false, "schema": { "type": "string", "description": "Payment directive (e.g., x402 payment ID)" } }, { "name": "ipBucket", "in": "query", "required": false, "schema": { "type": "string", "description": "The client's subnet bucket, forwarded by the upload service so the per-IP free-tier cap can be evaluated when committing a free grant." } } ], "responses": { "200": { "description": "OK - Balance reserved successfully", "content": { "text/plain": { "schema": { "type": "string", "description": "Reserved Winston amount", "example": "1000000" } } } }, "400": { "description": "Bad Request", "content": { "text/plain": { "schema": { "type": "string", "example": "Invalid parameters" } } } }, "401": { "description": "Unauthorized", "content": { "text/plain": { "schema": { "type": "string", "example": "Invalid authorization token" } } } }, "402": { "description": "Payment Required - Insufficient balance", "content": { "text/plain": { "schema": { "type": "string", "example": "Insufficient balance" } } } }, "404": { "description": "Not Found - User does not exist", "content": { "text/plain": { "schema": { "type": "string", "example": "User not found" } } } }, "503": { "description": "Service Unavailable", "content": { "text/plain": { "schema": { "type": "string", "example": "Error reserving balance" } } } } } } }, "/refund-balance/{token}/{signerAddress}": { "get": { "tags": [ "Protected" ], "summary": "Refund previously reserved balance", "description": "**PROTECTED ROUTE** - Requires `PRIVATE_ROUTE_SECRET` authentication header.\n\nRefunds Winston credits that were previously reserved for a data upload.\nCalled by the upload service when an upload fails or is canceled.\n\n**Authorization:** `x-auth-token` header must match `PRIVATE_ROUTE_SECRET` environment variable.\n", "parameters": [ { "name": "x-auth-token", "in": "header", "required": true, "schema": { "type": "string", "description": "Must match PRIVATE_ROUTE_SECRET" } }, { "name": "token", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TokenType" }, "description": "Currently unused (kept for backward compatibility)" }, { "name": "signerAddress", "in": "path", "required": true, "schema": { "type": "string", "description": "User's wallet address" } }, { "name": "winstonCredits", "in": "query", "required": true, "schema": { "type": "string", "description": "Winston amount to refund" } }, { "name": "dataItemId", "in": "query", "required": true, "schema": { "type": "string", "description": "Data item ID for the failed/canceled upload" } } ], "responses": { "200": { "description": "OK - Balance refunded successfully", "content": { "text/plain": { "schema": { "type": "string", "example": "Balance refunded" } } } }, "400": { "description": "Bad Request", "content": { "text/plain": { "schema": { "type": "string", "example": "Invalid parameters" } } } }, "401": { "description": "Unauthorized", "content": { "text/plain": { "schema": { "type": "string", "example": "Invalid authorization token" } } } }, "404": { "description": "Not Found - User does not exist", "content": { "text/plain": { "schema": { "type": "string", "example": "User not found" } } } }, "503": { "description": "Service Unavailable", "content": { "text/plain": { "schema": { "type": "string", "example": "Error refunding balance" } } } } } } }, "/check-balance/{token}/{signerAddress}": { "get": { "tags": [ "Protected" ], "summary": "Check if user has sufficient balance", "description": "**PROTECTED ROUTE** - Requires `PRIVATE_ROUTE_SECRET` authentication header.\n\nChecks whether a user has sufficient Winston credits for a given byte count upload.\nCalled by the upload service before accepting a data upload.\n\n**Authorization:** `x-auth-token` header must match `PRIVATE_ROUTE_SECRET` environment variable.\n", "parameters": [ { "name": "x-auth-token", "in": "header", "required": true, "schema": { "type": "string", "description": "Must match PRIVATE_ROUTE_SECRET" } }, { "name": "token", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TokenType" }, "description": "Currently unused (kept for backward compatibility)" }, { "name": "signerAddress", "in": "path", "required": true, "schema": { "type": "string", "description": "User's wallet address" } }, { "name": "byteCount", "in": "query", "required": true, "schema": { "type": "integer", "description": "Number of bytes to check" } }, { "name": "paidBy", "in": "query", "required": false, "schema": { "type": "string", "description": "Comma-separated list of addresses paying (delegated payment)" } }, { "name": "ipBucket", "in": "query", "required": false, "schema": { "type": "string", "description": "The client's subnet bucket, forwarded by the upload service so the per-IP free-tier cap can be evaluated." } } ], "responses": { "200": { "description": "OK - User has sufficient balance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckBalanceResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckBalanceResult" } } } }, "401": { "description": "Unauthorized", "content": { "text/plain": { "schema": { "type": "string", "example": "Invalid authorization token" } } } }, "402": { "description": "Payment Required - Insufficient balance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckBalanceResult" } } } }, "404": { "description": "Not Found - User does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckBalanceResult" } } } }, "503": { "description": "Service Unavailable", "content": { "text/plain": { "schema": { "type": "string", "example": "Error checking balance" } } } } } } }, "/account/approvals/create": { "get": { "tags": [ "Protected" ], "summary": "Create delegated payment approval", "description": "**PROTECTED ROUTE** - Requires `PRIVATE_ROUTE_SECRET` authentication header.\n\nCreates an approval allowing another address to spend credits from the paying address's balance.\nThis enables delegated payment scenarios where one user pays for another user's uploads.\n\n**Authorization:** `x-auth-token` header must match `PRIVATE_ROUTE_SECRET` environment variable.\n", "parameters": [ { "name": "x-auth-token", "in": "header", "required": true, "schema": { "type": "string", "description": "Must match PRIVATE_ROUTE_SECRET" } }, { "name": "payingAddress", "in": "query", "required": true, "schema": { "type": "string", "description": "Address that will pay" } }, { "name": "approvedAddress", "in": "query", "required": true, "schema": { "type": "string", "description": "Address that is approved to spend" } }, { "name": "approvedWincAmount", "in": "query", "required": true, "schema": { "type": "string", "description": "Winston amount approved" } }, { "name": "approvalDataItemId", "in": "query", "required": true, "schema": { "type": "string", "description": "Data item ID for the approval" } }, { "name": "expirationDate", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time", "description": "When the approval expires" } } ], "responses": { "200": { "description": "OK - Approval created successfully", "content": { "application/json": { "schema": { "type": "object", "description": "Created approval details" } } } }, "400": { "description": "Bad Request", "content": { "text/plain": { "schema": { "type": "string", "example": "Invalid parameters" } } } }, "401": { "description": "Unauthorized", "content": { "text/plain": { "schema": { "type": "string", "example": "Invalid authorization token" } } } }, "402": { "description": "Payment Required - Insufficient balance", "content": { "text/plain": { "schema": { "type": "string", "example": "Insufficient balance" } } } }, "503": { "description": "Service Unavailable", "content": { "text/plain": { "schema": { "type": "string", "example": "Error creating approval" } } } } } } }, "/account/approvals/revoke": { "get": { "tags": [ "Protected" ], "summary": "Revoke delegated payment approvals", "description": "**PROTECTED ROUTE** - Requires `PRIVATE_ROUTE_SECRET` authentication header.\n\nRevokes one or more delegated payment approvals, preventing the approved address from\nspending any more credits from the paying address.\n\n**Authorization:** `x-auth-token` header must match `PRIVATE_ROUTE_SECRET` environment variable.\n", "parameters": [ { "name": "x-auth-token", "in": "header", "required": true, "schema": { "type": "string", "description": "Must match PRIVATE_ROUTE_SECRET" } }, { "name": "payingAddress", "in": "query", "required": true, "schema": { "type": "string", "description": "Address that pays" } }, { "name": "approvedAddress", "in": "query", "required": true, "schema": { "type": "string", "description": "Address whose approval is being revoked" } }, { "name": "revokeDataItemId", "in": "query", "required": true, "schema": { "type": "string", "description": "Data item ID for the revocation" } } ], "responses": { "200": { "description": "OK - Approvals revoked successfully", "content": { "application/json": { "schema": { "type": "array", "description": "Revoked approval details", "items": { "type": "object" } } } } }, "400": { "description": "Bad Request", "content": { "text/plain": { "schema": { "type": "string", "example": "Invalid parameters" } } } }, "401": { "description": "Unauthorized", "content": { "text/plain": { "schema": { "type": "string", "example": "Invalid authorization token" } } } }, "503": { "description": "Service Unavailable", "content": { "text/plain": { "schema": { "type": "string", "example": "Error revoking approvals" } } } } } } }, "/stripe-webhook": { "post": { "tags": [ "Webhooks" ], "summary": "Stripe webhook for payment events", "description": "Receives webhook events from Stripe when payment events occur.\n\n**Supported Events:**\n- `payment_intent.succeeded` - Payment completed successfully, credits user's account\n- `charge.dispute.created` - Payment disputed, deducts credits if already credited\n\n**Security:** Webhook signature verification using Stripe webhook secret.\n\n**NOTE:** This endpoint is called directly by Stripe servers, not by clients.\n", "requestBody": { "required": true, "description": "Stripe webhook event payload", "content": { "application/json": { "schema": { "type": "object", "description": "Stripe Event object" } } } }, "responses": { "200": { "description": "OK - Event received and processed", "content": { "text/plain": { "schema": { "type": "string", "example": "OK" } } } }, "400": { "description": "Bad Request - Invalid signature", "content": { "text/plain": { "schema": { "type": "string", "example": "Webhook Error!" } } } } } } }, "/health": { "get": { "tags": [ "System" ], "summary": "Health check endpoint", "description": "Simple health check endpoint that returns \"OK\" if the service is running.\n\nUse this for:\n- Load balancer health checks\n- Monitoring/alerting systems\n- Service discovery\n", "responses": { "200": { "description": "OK - Service is healthy", "content": { "text/plain": { "schema": { "type": "string", "example": "OK" } } } } } } }, "/metrics": { "get": { "tags": [ "System" ], "summary": "Prometheus metrics endpoint", "description": "Returns Prometheus-formatted metrics for monitoring and observability.\n\n**Metrics Included:**\n- Default Node.js process metrics (CPU, memory, event loop, etc.)\n- Custom application metrics (payment success/failure counts, etc.)\n\n**Usage:** Configure Prometheus to scrape this endpoint periodically.\n", "responses": { "200": { "description": "OK - Prometheus metrics", "content": { "text/plain": { "schema": { "type": "string", "description": "Prometheus text exposition format", "example": "# HELP process_cpu_user_seconds_total Total user CPU time spent in seconds.\n# TYPE process_cpu_user_seconds_total counter\nprocess_cpu_user_seconds_total 0.123\n" } } } } } } }, "/price/{token}/{amount}": { "servers": [ { "url": "/" } ], "get": { "tags": [ "Pricing" ], "summary": "Arweave-compatible price endpoint (legacy)", "description": "**Legacy endpoint for ArConnect and ecosystem tool compatibility.**\n\nReturns the raw Winston credit amount as a plain string (not JSON).\nThis matches the format expected by ArConnect and other Arweave ecosystem tools.\n\n**Differences from /v1/price/bytes/{byteCount}:**\n- Returns plain string instead of JSON\n- No adjustments metadata\n- Kept for backward compatibility with existing tools\n", "parameters": [ { "name": "x-signature", "in": "header", "required": false, "schema": { "$ref": "#/components/schemas/SignatureHeader" } }, { "name": "x-nonce", "in": "header", "required": false, "schema": { "$ref": "#/components/schemas/NonceHeader" } }, { "name": "x-public-key", "in": "header", "required": false, "schema": { "$ref": "#/components/schemas/PublicKeyHeader" } }, { "name": "token", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TokenType" }, "description": "Currently unused, kept for compatibility" }, { "name": "amount", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ByteCount" }, "description": "Number of bytes" } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "type": "string", "description": "Winston credit amount as a plain string", "example": "1000000" } } } }, "400": { "description": "Bad Request", "content": { "text/plain": { "schema": { "type": "string", "example": "Invalid byte count" } } } }, "503": { "description": "Service Unavailable", "content": { "text/plain": { "schema": { "type": "string", "example": "Pricing Oracle Unavailable" } } } } } } } } }