{"openapi":"3.1.0","info":{"title":"SPL Private Payments API","version":"0.1.0","description":"REST API for building private SPL token transactions on Solana and MagicBlock ephemeral rollups.\n\n[MagicBlock private payments guide](https://docs.magicblock.gg/pages/private-ephemeral-rollups-pers/how-to-guide/quickstart)\n\n**Merchant checkout:** also supports [x402 v2](https://x402.org/) and [MPP](https://mpp.dev/) through custom MagicBlock payment methods for selling API access and products with delegated USDC. See the merchant checkout group below."},"tags":[{"name":"Swap","description":"Provide quoting and execution for public and private swaps."},{"name":"Meta"},{"name":"SPL"},{"name":"Transaction"},{"name":"MCP"},{"name":"Payments","x-displayName":"Merchants & checkouts","description":"For merchants selling API access or products through x402 or MPP: wallet registration, reusable offers, checkout preparation and shared payment status. Products and fulfillment remain in the merchant's service."},{"name":"x402","description":"Merchant checkout using x402 v2 with the custom exact-magicblock scheme: challenges, payment credentials and facilitator endpoints for delegated USDC."},{"name":"MPP","description":"Merchant checkout using MPP with the custom magicblock method and charge intent: Payment challenges and receipts for delegated USDC."}],"x-tagGroups":[{"name":"Core API","tags":["Swap","Meta","SPL","Transaction","MCP"]},{"name":"Merchant checkout · x402 / MPP","tags":["Payments","x402","MPP"]}],"components":{"schemas":{"HealthResponse":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]}},"required":["status"]},"UnsignedTransactionResponse":{"type":"object","properties":{"kind":{"type":"string","enum":["deposit","withdraw","transfer","initializeMint","undelegateEphemeralAta","stealthPool"]},"version":{"type":"string","enum":["legacy","v0"]},"transactionBase64":{"type":"string"},"sendTo":{"$ref":"#/components/schemas/BalanceLocation"},"sendRpcEndpoint":{"type":"string","format":"uri","description":"Exact ephemeral RPC endpoint where the signed transaction should be submitted. Present when `sendTo` is `ephemeral`."},"from":{"$ref":"#/components/schemas/BalanceLocation"},"recentBlockhash":{"type":"string"},"lastValidBlockHeight":{"type":"integer"},"instructionCount":{"type":"integer","minimum":0},"requiredSigners":{"type":"array","items":{"type":"string","example":"So11111111111111111111111111111111111111112"}},"validator":{"type":"string","example":"So11111111111111111111111111111111111111112"},"fees":{"$ref":"#/components/schemas/TransferFees"}},"required":["kind","version","transactionBase64","sendTo","recentBlockhash","lastValidBlockHeight","instructionCount","requiredSigners"]},"BalanceLocation":{"type":"string","enum":["base","ephemeral"]},"TransferFees":{"type":"object","properties":{"lamports":{"type":"string","example":"2039280","description":"Operation lamport fees, excluding network fees and account rent. Paid by the sponsor for gasless transactions. Returns \"0\" when no lamport fee is charged."},"tokens":{"type":"string","example":"205000","description":"Total token fees charged by the operation, in mint base units. Returns \"0\" when no token fee is charged."}},"required":["lamports","tokens"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]},"ValidationErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR"]},"message":{"type":"string"},"issues":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}}},"required":["code","message","path"]}}},"required":["code","message","issues"]}},"required":["error"]},"DepositRequest":{"type":"object","properties":{"owner":{"type":"string","example":"3rXKwQ1kpjBd5tdcco32qsvqUh1BnZjcYnS5kYrP7AYE"},"cluster":{"anyOf":[{"type":"string","enum":["mainnet","devnet","mainnet-private","devnet-private"]},{"type":"string","format":"uri"}],"example":"mainnet","description":"Optional, defaults to `mainnet`. `mainnet` and `devnet` route to the public ephemeral RPC for that network; `mainnet-private` and `devnet-private` route to the TEE-backed Private Ephemeral Rollup and are required for auth and bearer-token-gated reads. A custom http(s) RPC URL overrides only the base RPC while keeping the configured ephemeral RPC."},"mint":{"type":"string","example":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","description":"Optional. Defaults to Solana USDC on mainnet: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v. On devnet and devnet-private it defaults to devnet USDC: 4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU."},"amount":{"type":"integer","minimum":1,"example":1,"description":"Base-unit amount as an integer JSON value with minimum 1."},"gasless":{"type":"boolean","example":true,"description":"Optional. Defaults to false. Uses the configured sponsor as payer and charges 0.2 USDC/USDT from the owner's existing base-chain ATA, in addition to amount. Requires GASLESS_SPONSOR_SECRET_KEY, an existing sponsor ATA, an on-curve owner, mainnet USDC/USDT or devnet USDC (including private clusters), and amount of at least 0.5 tokens. Custom clusters are unsupported. The returned transaction includes the sponsor signature; the owner must still sign."},"validator":{"type":"string","example":"MAS1Dt9qreoRMQ14YQuhg8UTZMMzDdKhmkZMECCzk57","description":"Optional. Defaults to the selected ephemeral RPC identity resolved via `getIdentity`."},"initIfMissing":{"type":"boolean"},"initVaultIfMissing":{"type":"boolean"},"initAtasIfMissing":{"type":"boolean"},"idempotent":{"type":"boolean"},"private":{"type":"boolean","example":true,"description":"Optional. Defaults to true. When true, adds the private eATA permission instruction."}},"required":["owner","amount"],"example":{"owner":"3rXKwQ1kpjBd5tdcco32qsvqUh1BnZjcYnS5kYrP7AYE","amount":1,"initIfMissing":true,"initVaultIfMissing":false,"initAtasIfMissing":true,"idempotent":true,"private":true}},"WithdrawRequest":{"type":"object","properties":{"owner":{"type":"string","example":"3rXKwQ1kpjBd5tdcco32qsvqUh1BnZjcYnS5kYrP7AYE"},"cluster":{"anyOf":[{"type":"string","enum":["mainnet","devnet","mainnet-private","devnet-private"]},{"type":"string","format":"uri"}],"example":"mainnet","description":"Optional, defaults to `mainnet`. `mainnet` and `devnet` route to the public ephemeral RPC for that network; `mainnet-private` and `devnet-private` route to the TEE-backed Private Ephemeral Rollup and are required for auth and bearer-token-gated reads. A custom http(s) RPC URL overrides only the base RPC while keeping the configured ephemeral RPC."},"mint":{"type":"string","example":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","description":"SPL mint on Solana."},"amount":{"type":"integer","minimum":1,"example":1000000,"description":"Base-unit amount as an integer JSON value with minimum 1."},"gasless":{"type":"boolean","example":true,"description":"Optional. Defaults to false. Uses the configured sponsor as payer and charges 0.2 USDC/USDT from the owner's existing base-chain ATA, in addition to amount. Requires GASLESS_SPONSOR_SECRET_KEY, an existing sponsor ATA, an on-curve owner, mainnet USDC/USDT or devnet USDC (including private clusters), and amount of at least 0.5 tokens. Custom clusters are unsupported. The returned transaction includes the sponsor signature; the owner must still sign."},"feeBalance":{"allOf":[{"$ref":"#/components/schemas/BalanceLocation"},{"example":"ephemeral","description":"Optional. Defaults to base. With gasless=true and ephemeral, the 0.2 USDC/USDT relay fee is deducted from amount inside the ephemeral rollup instead of the base-chain ATA, so the owner needs no base-chain funds and receives amount minus the fee. The fee goes to the transfer-queue vault. Requires the idempotent flow."}]},"validator":{"type":"string","example":"MAS1Dt9qreoRMQ14YQuhg8UTZMMzDdKhmkZMECCzk57","description":"Optional. Defaults to the selected ephemeral RPC identity resolved via `getIdentity`."},"initIfMissing":{"type":"boolean"},"initAtasIfMissing":{"type":"boolean"},"escrowIndex":{"type":"integer","minimum":0},"idempotent":{"type":"boolean"}},"required":["owner","mint","amount"],"example":{"owner":"3rXKwQ1kpjBd5tdcco32qsvqUh1BnZjcYnS5kYrP7AYE","mint":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","amount":1000000,"idempotent":true}},"InitializeMintResponse":{"allOf":[{"$ref":"#/components/schemas/UnsignedTransactionResponse"},{"type":"object","properties":{"kind":{"type":"string","enum":["initializeMint"]},"transferQueue":{"type":"string","example":"So11111111111111111111111111111111111111112"},"rentPda":{"type":"string","example":"So11111111111111111111111111111111111111112"}},"required":["validator","transferQueue","rentPda"]}]},"InitializeMintRequest":{"type":"object","properties":{"payer":{"type":"string","example":"3rXKwQ1kpjBd5tdcco32qsvqUh1BnZjcYnS5kYrP7AYE"},"mint":{"type":"string","example":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"},"cluster":{"anyOf":[{"type":"string","enum":["mainnet","devnet","mainnet-private","devnet-private"]},{"type":"string","format":"uri"}],"example":"mainnet","description":"Optional, defaults to `mainnet`. `mainnet` and `devnet` route to the public ephemeral RPC for that network; `mainnet-private` and `devnet-private` route to the TEE-backed Private Ephemeral Rollup and are required for auth and bearer-token-gated reads. A custom http(s) RPC URL overrides only the base RPC while keeping the configured ephemeral RPC."},"validator":{"type":"string","example":"MAS1Dt9qreoRMQ14YQuhg8UTZMMzDdKhmkZMECCzk57","description":"Optional. Defaults to the selected ephemeral RPC identity resolved via `getIdentity`."}},"required":["payer","mint"],"example":{"payer":"3rXKwQ1kpjBd5tdcco32qsvqUh1BnZjcYnS5kYrP7AYE","mint":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","validator":"MAS1Dt9qreoRMQ14YQuhg8UTZMMzDdKhmkZMECCzk57"}},"TransferRequest":{"type":"object","properties":{"from":{"type":"string","example":"So11111111111111111111111111111111111111112"},"to":{"type":"string","minLength":1,"example":"Bt9oNR5cCtnfuMmXgWELd6q5i974PdEMQDUE55nBC57L","description":"Destination owner public key, or an initialized stealth handle for private base-to-base transfers."},"cluster":{"anyOf":[{"type":"string","enum":["mainnet","devnet","mainnet-private","devnet-private"]},{"type":"string","format":"uri"}],"example":"mainnet","description":"Optional, defaults to `mainnet`. `mainnet` and `devnet` route to the public ephemeral RPC for that network; `mainnet-private` and `devnet-private` route to the TEE-backed Private Ephemeral Rollup and are required for auth and bearer-token-gated reads. A custom http(s) RPC URL overrides only the base RPC while keeping the configured ephemeral RPC."},"mint":{"type":"string","example":"So11111111111111111111111111111111111111112"},"amount":{"type":"integer","minimum":0,"example":1000000,"description":"Base-unit amount as a non-negative integer JSON value."},"visibility":{"$ref":"#/components/schemas/TransferVisibility"},"fromBalance":{"$ref":"#/components/schemas/BalanceLocation"},"toBalance":{"$ref":"#/components/schemas/BalanceLocation"},"validator":{"type":"string","example":"MAS1Dt9qreoRMQ14YQuhg8UTZMMzDdKhmkZMECCzk57","description":"Optional. When this transfer route needs a validator and none is provided, the API resolves it from the selected ephemeral RPC via `getIdentity`."},"initIfMissing":{"type":"boolean"},"initAtasIfMissing":{"type":"boolean"},"initVaultIfMissing":{"type":"boolean"},"memo":{"type":"string","example":"Order #1042","description":"Optional. Appends a final Memo Program instruction with this UTF-8 message."},"minDelayMs":{"type":"string","example":"0","description":"Optional. Private transfer only. Defaults to 0."},"maxDelayMs":{"type":"string","example":"0","description":"Optional. Private transfer only. Defaults to 0 when omitted, or to minDelayMs when minDelayMs is set."},"clientRefId":{"type":"string","example":"42","description":"Optional. Private transfer only. Encrypted client reference ID that can be used to confirm a payment."},"split":{"type":"integer","exclusiveMinimum":0,"maximum":15,"example":1,"description":"Optional. Private transfer only. Defaults to 1. Must be between 1 and 15."},"exactOut":{"type":"boolean","description":"Optional. If true, the fees are deducted from the sender, else from the recipient amount"},"platformFeeBps":{"type":"integer","minimum":0,"maximum":10000,"example":100,"description":"Optional platform fee in basis points, charged in the transferred token."},"platformFeeAccount":{"type":"string","example":"6QxLzE2KfM1NAB7sTzUPk4cNsA6V9fB3eYq9s6d9r9hP","description":"Required when platformFeeBps is greater than 0. Token account (not a wallet address) that collects the platform fee, for the transferred mint — e.g. the fee collector's USDC ATA for a USDC transfer, or their WSOL ATA for native SOL transfers. Expected to already exist on-chain; the API does not verify it, so a wallet address, uninitialized ATA, or wrong-mint token account still returns 200 and the built transaction fails at simulation with an SPL Token error."},"gasless":{"type":"boolean","example":true,"description":"Optional. When true, the API uses the configured sponsor as transaction fee payer and prepends a 0.2 USDC/USDT relay-fee token transfer to the sponsor ATA. Requires GASLESS_SPONSOR_SECRET_KEY, an approved stablecoin mint (mainnet USDC/USDT or devnet USDC), and at least 0.5 USDC/USDT."},"legacy":{"type":"boolean","description":"Optional. Defaults to false. When true, skips lookup-table compilation and returns a legacy transaction."}},"required":["from","to","mint","amount"],"example":{"from":"3rXKwQ1kpjBd5tdcco32qsvqUh1BnZjcYnS5kYrP7AYE","to":"Bt9oNR5cCtnfuMmXgWELd6q5i974PdEMQDUE55nBC57L","mint":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","amount":500000,"visibility":"private","fromBalance":"base","toBalance":"base","memo":"Order #1042","minDelayMs":"0","maxDelayMs":"0","clientRefId":"42","gasless":true}},"TransferVisibility":{"type":"string","enum":["public","private"],"default":"private"},"UndelegateEphemeralAtaResponse":{"allOf":[{"$ref":"#/components/schemas/UnsignedTransactionResponse"},{"type":"object","properties":{"kind":{"type":"string","enum":["undelegateEphemeralAta"]},"sendRpcEndpoint":{"type":"string","format":"uri","description":"Exact ephemeral RPC endpoint where the signed undelegation transaction should be submitted."}},"required":["sendRpcEndpoint"]}]},"UndelegateEphemeralAtaRequest":{"type":"object","properties":{"payer":{"type":"string","example":"3rXKwQ1kpjBd5tdcco32qsvqUh1BnZjcYnS5kYrP7AYE"},"mint":{"type":"string","example":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","description":"SPL mint for the eATA to undelegate."},"cluster":{"anyOf":[{"type":"string","enum":["mainnet","devnet","mainnet-private","devnet-private"]},{"type":"string","format":"uri"}],"example":"mainnet","description":"Optional, defaults to `mainnet`. `mainnet` and `devnet` route to the public ephemeral RPC for that network; `mainnet-private` and `devnet-private` route to the TEE-backed Private Ephemeral Rollup and are required for auth and bearer-token-gated reads. A custom http(s) RPC URL overrides only the base RPC while keeping the configured ephemeral RPC."}},"required":["payer","mint"],"example":{"payer":"3rXKwQ1kpjBd5tdcco32qsvqUh1BnZjcYnS5kYrP7AYE","mint":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"}},"StealthPoolResponse":{"allOf":[{"$ref":"#/components/schemas/UnsignedTransactionResponse"},{"type":"object","properties":{"kind":{"type":"string","enum":["stealthPool"]},"setupTransaction":{"$ref":"#/components/schemas/UnsignedTransactionResponse"},"stealthPool":{"type":"string","example":"So11111111111111111111111111111111111111112"}},"required":["setupTransaction","stealthPool"]}]},"StealthPoolRequest":{"type":"object","properties":{"payer":{"type":"string","example":"3rXKwQ1kpjBd5tdcco32qsvqUh1BnZjcYnS5kYrP7AYE"},"authority":{"type":"string","example":"3rXKwQ1kpjBd5tdcco32qsvqUh1BnZjcYnS5kYrP7AYE"},"handle":{"type":"string","minLength":1,"example":"john.doe@magicblock.id","description":"Exact canonical handle string, up to 255 UTF-8 bytes. The API derives the stealth-pool PDA from these UTF-8 bytes as-is; it does not trim, lowercase, or normalize."},"destinations":{"type":"array","items":{"type":"string","example":"So11111111111111111111111111111111111111112"},"minItems":1,"maxItems":10,"example":["Bt9oNR5cCtnfuMmXgWELd6q5i974PdEMQDUE55nBC57L","3rXKwQ1kpjBd5tdcco32qsvqUh1BnZjcYnS5kYrP7AYE"],"description":"Owner public keys, not token accounts. Must contain between 1 and 10 keys."},"splitAcrossKeys":{"type":"boolean","example":false,"description":"Optional. When true, split payments may resolve independently across destination keys."},"validator":{"type":"string","example":"MAS1Dt9qreoRMQ14YQuhg8UTZMMzDdKhmkZMECCzk57","description":"Optional validator identity to receive the delegated stealth pool."},"cluster":{"anyOf":[{"type":"string","enum":["mainnet","devnet","mainnet-private","devnet-private"]},{"type":"string","format":"uri"}],"example":"mainnet","description":"Optional, defaults to `mainnet`. `mainnet` and `devnet` route to the public ephemeral RPC for that network; `mainnet-private` and `devnet-private` route to the TEE-backed Private Ephemeral Rollup and are required for auth and bearer-token-gated reads. A custom http(s) RPC URL overrides only the base RPC while keeping the configured ephemeral RPC."}},"required":["payer","authority","handle","destinations"],"example":{"payer":"3rXKwQ1kpjBd5tdcco32qsvqUh1BnZjcYnS5kYrP7AYE","authority":"3rXKwQ1kpjBd5tdcco32qsvqUh1BnZjcYnS5kYrP7AYE","handle":"john.doe@magicblock.id","destinations":["Bt9oNR5cCtnfuMmXgWELd6q5i974PdEMQDUE55nBC57L"],"splitAcrossKeys":false,"validator":"MAS1Dt9qreoRMQ14YQuhg8UTZMMzDdKhmkZMECCzk57"}},"StealthPoolStatusResponse":{"type":"object","properties":{"stealthPool":{"type":"string","example":"So11111111111111111111111111111111111111112"},"exists":{"type":"boolean"}},"required":["stealthPool","exists"]},"BalanceResponse":{"type":"object","properties":{"address":{"type":"string","example":"So11111111111111111111111111111111111111112"},"mint":{"type":"string","example":"So11111111111111111111111111111111111111112"},"ata":{"type":"string","example":"So11111111111111111111111111111111111111112"},"location":{"$ref":"#/components/schemas/BalanceLocation"},"balance":{"type":"string"},"delegation":{"$ref":"#/components/schemas/BalanceDelegation"}},"required":["address","mint","ata","location","balance"]},"BalanceDelegation":{"oneOf":[{"type":"object","properties":{"status":{"type":"string","enum":["delegated"]},"validator":{"type":"string","example":"So11111111111111111111111111111111111111112","description":"Identity of the validator the eATA is currently delegated to."},"endpoint":{"type":"string","format":"uri","description":"Ephemeral RPC endpoint serving the delegated eATA, when it can be resolved without extra lookups."}},"required":["status","validator"]},{"type":"object","properties":{"status":{"type":"string","enum":["undelegated"]}},"required":["status"]}],"description":"Delegation state of the owner's eATA for this mint, read from the base-layer delegation record."},"MintInitializationResponse":{"type":"object","properties":{"mint":{"type":"string","example":"So11111111111111111111111111111111111111112"},"validator":{"type":"string","example":"So11111111111111111111111111111111111111112"},"transferQueue":{"type":"string","example":"So11111111111111111111111111111111111111112"},"initialized":{"type":"boolean"}},"required":["mint","validator","transferQueue","initialized"]},"TransferQueueEnsureCrankResponse":{"type":"object","properties":{"mint":{"type":"string","example":"So11111111111111111111111111111111111111112"},"validator":{"type":"string","example":"So11111111111111111111111111111111111111112"},"transferQueue":{"type":"string","example":"So11111111111111111111111111111111111111112"},"crankSignature":{"type":"string"}},"required":["mint","validator","transferQueue","crankSignature"]},"TransferQueueEnsureCrankRequest":{"type":"object","properties":{"mint":{"type":"string","example":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"},"cluster":{"anyOf":[{"type":"string","enum":["mainnet","devnet","mainnet-private","devnet-private"]},{"type":"string","format":"uri"}],"example":"mainnet","description":"Optional, defaults to `mainnet`. `mainnet` and `devnet` route to the public ephemeral RPC for that network; `mainnet-private` and `devnet-private` route to the TEE-backed Private Ephemeral Rollup and are required for auth and bearer-token-gated reads. A custom http(s) RPC URL overrides only the base RPC while keeping the configured ephemeral RPC."},"validator":{"type":"string","example":"MAS1Dt9qreoRMQ14YQuhg8UTZMMzDdKhmkZMECCzk57","description":"Optional. Defaults to the selected ephemeral RPC identity resolved via `getIdentity`."}},"required":["mint"],"example":{"mint":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","validator":"MAS1Dt9qreoRMQ14YQuhg8UTZMMzDdKhmkZMECCzk57"}},"SwapQuoteResponse":{"type":"object","properties":{"inputMint":{"type":"string"},"inAmount":{"type":"string","pattern":"^\\d+$"},"outputMint":{"type":"string"},"outAmount":{"type":"string","pattern":"^\\d+$"},"otherAmountThreshold":{"type":"string","pattern":"^\\d+$"},"swapMode":{"$ref":"#/components/schemas/SwapMode"},"slippageBps":{"type":"integer","minimum":0},"priceImpactPct":{"type":"string"},"routePlan":{"type":"array","items":{"type":"object","properties":{"swapInfo":{"type":"object","properties":{"ammKey":{"type":"string"},"inputMint":{"type":"string"},"outputMint":{"type":"string"},"inAmount":{"type":"string","pattern":"^\\d+$"},"outAmount":{"type":"string","pattern":"^\\d+$"},"label":{"type":"string"},"outAmountAfterSlippage":{"type":"string","pattern":"^\\d+$"}},"required":["ammKey","inputMint","outputMint","inAmount","outAmount","label"],"additionalProperties":{}},"percent":{"type":"integer","minimum":0},"bps":{"type":["integer","null"],"minimum":0}},"required":["swapInfo","percent","bps"],"additionalProperties":{}}},"instructionVersion":{"$ref":"#/components/schemas/InstructionVersion"},"platformFee":{"type":["object","null"],"properties":{"amount":{"type":"string","pattern":"^\\d+$"},"feeBps":{"type":"integer","minimum":0}},"required":["amount","feeBps"],"additionalProperties":{}},"contextSlot":{"type":"integer","minimum":0},"timeTaken":{"type":"number"},"additionalIntermediateTokens":{"type":["array","null"],"items":{"type":"string"}}},"required":["inputMint","inAmount","outputMint","outAmount","otherAmountThreshold","swapMode","slippageBps","priceImpactPct","routePlan"],"additionalProperties":{}},"SwapMode":{"type":"string","enum":["ExactIn","ExactOut"]},"InstructionVersion":{"type":["string","null"],"enum":["V1","V2",null]},"SwapResponse":{"type":"object","properties":{"swapTransaction":{"type":"string"},"lastValidBlockHeight":{"type":"integer","minimum":0},"prioritizationFeeLamports":{"type":"integer","minimum":0},"privateTransfer":{"type":"object","properties":{"stashAta":{"type":"string"},"hydraCrankPda":{"type":"string"},"shuttleId":{"type":"integer","minimum":0}},"required":["stashAta","hydraCrankPda","shuttleId"],"description":"Present when visibility=private. Diagnostic metadata about the appended schedule_private_transfer instruction."}},"required":["swapTransaction"],"additionalProperties":{}},"SwapRequest":{"type":"object","properties":{"userPublicKey":{"type":"string","example":"3rXKwQ1kpjBd5tdcco32qsvqUh1BnZjcYnS5kYrP7AYE","description":"Public key of the wallet that will sign the swap transaction."},"quoteResponse":{"$ref":"#/components/schemas/SwapQuoteResponse"},"payer":{"type":"string","example":"3rXKwQ1kpjBd5tdcco32qsvqUh1BnZjcYnS5kYrP7AYE","description":"Optional fee payer for transaction fees and rent."},"wrapAndUnwrapSol":{"type":"boolean","example":true,"description":"Automatically wrap and unwrap native SOL when needed."},"useSharedAccounts":{"type":"boolean","example":true,"description":"Allow shared accounts for intermediate routing state."},"feeAccount":{"type":"string","example":"6QxLzE2KfM1NAB7sTzUPk4cNsA6V9fB3eYq9s6d9r9hP","description":"Optional initialized token account used to collect platform fees."},"trackingAccount":{"type":"string","example":"Bt9oNR5cCtnfuMmXgWELd6q5i974PdEMQDUE55nBC57L","description":"Optional public key used for downstream transaction tracking."},"prioritizationFeeLamports":{"anyOf":[{"type":"integer","minimum":0},{"type":"object","properties":{"priorityLevelWithMaxLamports":{"type":"object","properties":{"priorityLevel":{"type":"string"},"maxLamports":{"type":"integer","minimum":0},"global":{"type":"boolean"}},"required":["priorityLevel","maxLamports"]},"jitoTipLamports":{"type":"integer","minimum":0},"jitoTipLamportsWithPayer":{"type":"integer","minimum":0}},"additionalProperties":{}}],"description":"Optional priority fee configuration or fixed lamport amount."},"asLegacyTransaction":{"type":"boolean","example":false,"description":"Build a legacy transaction instead of a versioned one."},"destinationTokenAccount":{"type":"string","example":"6QxLzE2KfM1NAB7sTzUPk4cNsA6V9fB3eYq9s6d9r9hP","description":"Optional destination token account for the output mint."},"nativeDestinationAccount":{"type":"string","example":"Bt9oNR5cCtnfuMmXgWELd6q5i974PdEMQDUE55nBC57L","description":"Optional destination account for native SOL output."},"dynamicComputeUnitLimit":{"type":"boolean","example":false,"description":"Estimate compute usage and set the compute unit limit automatically."},"skipUserAccountsRpcCalls":{"type":"boolean","example":false,"description":"Skip extra RPC checks for required user accounts."},"dynamicSlippage":{"type":"boolean","example":false,"description":"Let the upstream swap builder overwrite slippage on the transaction."},"computeUnitPriceMicroLamports":{"type":"integer","minimum":0,"example":1000,"description":"Optional exact compute unit price in micro-lamports."},"blockhashSlotsToExpiry":{"type":"integer","minimum":0,"example":10,"description":"Optional transaction expiry window in slots."},"positiveSlippage":{"type":"object","properties":{"bps":{"type":"integer","minimum":0},"feeAccount":{"type":"string"}},"required":["bps"],"additionalProperties":{},"description":"Optional positive slippage collection settings."},"visibility":{"type":"string","enum":["public","private"],"example":"public","description":"Public swap (default) proxies Jupiter/Metis as-is. `private` forces Jupiter's output into a program-owned stash ATA and appends a scheduled private transfer."},"destination":{"type":"string","example":"3rXKwQ1kpjBd5tdcco32qsvqUh1BnZjcYnS5kYrP7AYE","description":"Final private-transfer recipient (wallet pubkey). Required when visibility=private."},"minDelayMs":{"type":"string","pattern":"^\\d+$","example":"0","description":"Earliest (ms) the queued transfer may settle. Required when visibility=private."},"maxDelayMs":{"type":"string","pattern":"^\\d+$","example":"60000","description":"Latest (ms) the queued transfer may settle. Required when visibility=private."},"split":{"type":"integer","exclusiveMinimum":0,"example":1,"description":"Number of queue entries to split the transfer across. Required when visibility=private. Must be between 1 and 14."},"clientRefId":{"type":"string","pattern":"^\\d+$","example":"0","description":"Optional u64 client correlation id attached to each queued split."},"validator":{"type":"string","example":"MAS1Dt9qreoRMQ14YQuhg8UTZMMzDdKhmkZMECCzk57","description":"Optional validator pubkey for the transfer-queue PDA. Defaults to the well-known MagicBlock validator."}},"required":["userPublicKey","quoteResponse"],"additionalProperties":{}},"SendTransactionResponse":{"type":"object","properties":{"signature":{"type":"string"},"sendTo":{"$ref":"#/components/schemas/BalanceLocation"},"confirmed":{"type":"boolean"},"confirmationRpcEndpoint":{"type":"string","format":"uri"},"confirmationRequiresAuthToken":{"type":"boolean"}},"required":["signature","sendTo","confirmed","confirmationRpcEndpoint","confirmationRequiresAuthToken"]},"SendTransactionRequest":{"type":"object","properties":{"transactionBase64":{"type":"string","minLength":1,"example":"AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAA==","description":"Signed serialized Solana transaction encoded as base64."},"sendTo":{"allOf":[{"$ref":"#/components/schemas/BalanceLocation"},{"description":"RPC target for submission. Use the `sendTo` value returned by transaction-builder endpoints."}]},"sendRpcEndpoint":{"type":"string","format":"uri","description":"Optional exact ephemeral RPC endpoint returned by transaction-builder endpoints. Only valid when `sendTo` is `ephemeral`."},"cluster":{"anyOf":[{"type":"string","enum":["mainnet","devnet","mainnet-private","devnet-private"]},{"type":"string","format":"uri"}],"example":"mainnet","description":"Optional, defaults to `mainnet`. `mainnet` and `devnet` route to the public ephemeral RPC for that network; `mainnet-private` and `devnet-private` route to the TEE-backed Private Ephemeral Rollup and are required for auth and bearer-token-gated reads. A custom http(s) RPC URL overrides only the base RPC while keeping the configured ephemeral RPC."},"confirm":{"type":"boolean","example":false,"description":"Optional. Defaults to false. When true, `recentBlockhash` and `lastValidBlockHeight` are required."},"recentBlockhash":{"type":"string","example":"9A4VhP8M8fQZxP4h7rB6mP6eM8w2pJkYh7QdZk7V4r2x","description":"Optional. Required only when `confirm` is true."},"lastValidBlockHeight":{"type":"integer","minimum":0,"example":284512337,"description":"Optional. Required only when `confirm` is true."},"skipPreflight":{"type":"boolean"},"maxRetries":{"type":"integer","minimum":0}},"required":["transactionBase64","sendTo"],"example":{"transactionBase64":"AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAA==","sendTo":"base"}},"McpResponse":{"type":"object","properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"id":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"null"}]},"result":{},"error":{"type":"object","properties":{"code":{"type":"number"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":{}}},"required":["jsonrpc"],"additionalProperties":{},"example":{"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"Built an unsigned SPL deposit transaction."}],"structuredContent":{"kind":"deposit","version":"legacy","transactionBase64":"AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAAIDKmcfsS5XfSOLaLlaBHJry50iH2Ufk2TMz4STC2fHzIcFKkerg3q2DD3Yn8TISmGeKoxSLz+BiP7iQ4pYqXYXsgu8D8C7R8ovdMQRLpSrE8+jxjTl3BfqywPNGiPNfnh8eS+smowIxqKDcCjw5liNXQkkCbBSDCBDFwtrgCKqoQ0DAgEBBAECAwQCAQEEAgIDBAIBAQQDAgME","sendTo":"base","recentBlockhash":"9A4VhP8M8fQZxP4h7rB6mP6eM8w2pJkYh7QdZk7V4r2x","lastValidBlockHeight":284512337,"instructionCount":3,"requiredSigners":["3rXKwQ1kpjBd5tdcco32qsvqUh1BnZjcYnS5kYrP7AYE"],"validator":"MAS1Dt9qreoRMQ14YQuhg8UTZMMzDdKhmkZMECCzk57"}}}}},"parameters":{}},"paths":{"/health":{"get":{"tags":["Meta"],"responses":{"200":{"description":"Health check","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/v1/spl/deposit":{"post":{"tags":["SPL"],"description":"Deposit SPL tokens from Solana into an ephemeral rollup. Optional gasless sponsorship charges the relay fee from the owner's existing base-chain token balance.","requestBody":{"required":true,"description":"Deposit request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DepositRequest"}}}},"responses":{"200":{"description":"Unsigned or partially signed serialized transaction","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsignedTransactionResponse"},"example":{"kind":"deposit","version":"legacy","transactionBase64":"AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAAIDKmcfsS5XfSOLaLlaBHJry50iH2Ufk2TMz4STC2fHzIcFKkerg3q2DD3Yn8TISmGeKoxSLz+BiP7iQ4pYqXYXsgu8D8C7R8ovdMQRLpSrE8+jxjTl3BfqywPNGiPNfnh8eS+smowIxqKDcCjw5liNXQkkCbBSDCBDFwtrgCKqoQ0DAgEBBAECAwQCAQEEAgIDBAIBAQQDAgME","sendTo":"base","recentBlockhash":"9A4VhP8M8fQZxP4h7rB6mP6eM8w2pJkYh7QdZk7V4r2x","lastValidBlockHeight":284512337,"instructionCount":3,"requiredSigners":["3rXKwQ1kpjBd5tdcco32qsvqUh1BnZjcYnS5kYrP7AYE"],"validator":"MAS1Dt9qreoRMQ14YQuhg8UTZMMzDdKhmkZMECCzk57"}}}},"400":{"description":"Build error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"503":{"description":"Sponsor unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/spl/withdraw":{"post":{"tags":["SPL"],"description":"Withdraw SPL tokens from an ephemeral rollup back to Solana. Optional gasless sponsorship charges the relay fee from the owner's existing base-chain token balance before withdrawal.","parameters":[{"schema":{"type":"string","example":"Bearer 1234567890","description":"Optional. Authentication token for requests that need to connect to the Private Ephemeral Rollup."},"required":false,"description":"Optional. Authentication token for requests that need to connect to the Private Ephemeral Rollup.","name":"authorization","in":"header"}],"requestBody":{"required":true,"description":"Withdraw request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WithdrawRequest"}}}},"responses":{"200":{"description":"Unsigned or partially signed serialized transaction","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsignedTransactionResponse"},"example":{"kind":"withdraw","version":"legacy","transactionBase64":"AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAAIDKmcfsS5XfSOLaLlaBHJry50iH2Ufk2TMz4STC2fHzIcFKkerg3q2DD3Yn8TISmGeKoxSLz+BiP7iQ4pYqXYXsgu8D8C7R8ovdMQRLpSrE8+jxjTl3BfqywPNGiPNfnh8AazZ0ixOauLjpxaRgDCv6MChaoMAZAJg8BnPbZl31jECAgEBBAECAwQCAQEEAgIDBA==","sendTo":"base","recentBlockhash":"7YH7nE6qj8vH3L9pR5uM2cD1xK4sT8wQ6bN3fJ2mP9z","lastValidBlockHeight":284512451,"instructionCount":2,"requiredSigners":["3rXKwQ1kpjBd5tdcco32qsvqUh1BnZjcYnS5kYrP7AYE"],"validator":"MAS1Dt9qreoRMQ14YQuhg8UTZMMzDdKhmkZMECCzk57"}}}},"400":{"description":"Build error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Token identity mismatch","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"503":{"description":"Sponsor unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/spl/initialize-mint":{"post":{"tags":["SPL"],"description":"Build an unsigned base-chain transaction that initializes and delegates a validator-scoped transfer queue for a mint.","requestBody":{"required":true,"description":"Initialize mint request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InitializeMintRequest"}}}},"responses":{"200":{"description":"Unsigned serialized transaction","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InitializeMintResponse"},"example":{"kind":"initializeMint","version":"legacy","transactionBase64":"AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAAIDKmcfsS5XfSOLaLlaBHJry50iH2Ufk2TMz4STC2fHzIcFKkerg3q2DD3Yn8TISmGeKoxSLz+BiP7iQ4pYqXYXsgu8D8C7R8ovdMQRLpSrE8+jxjTl3BfqywPNGiPNfnh8eS+smowIxqKDcCjw5liNXQkkCbBSDCBDFwtrgCKqoQ0DAgEBBAECAwQCAQEEAgIDBAIBAQQDAgME","sendTo":"base","recentBlockhash":"9A4VhP8M8fQZxP4h7rB6mP6eM8w2pJkYh7QdZk7V4r2x","lastValidBlockHeight":284512337,"instructionCount":7,"requiredSigners":["3rXKwQ1kpjBd5tdcco32qsvqUh1BnZjcYnS5kYrP7AYE"],"validator":"MAS1Dt9qreoRMQ14YQuhg8UTZMMzDdKhmkZMECCzk57","transferQueue":"BuBHLbaPmYmgvMiZ8uZb96RjBtmWzJY52u7Di5urNf6M","rentPda":"Bt9oNR5cCtnfuMmXgWELd6q5i974PdEMQDUE55nBC57L"}}}},"400":{"description":"Build error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}}}}},"/v1/spl/transfer":{"post":{"tags":["SPL"],"description":"Transfer SPL tokens publicly, privately, or to an initialized stealth handle through an ephemeral rollup.","parameters":[{"schema":{"type":"string","example":"Bearer 1234567890","description":"Optional. Authentication token for requests that need to connect to the Private Ephemeral Rollup."},"required":false,"description":"Optional. Authentication token for requests that need to connect to the Private Ephemeral Rollup.","name":"authorization","in":"header"}],"requestBody":{"required":true,"description":"Transfer request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransferRequest"}}}},"responses":{"200":{"description":"Unsigned serialized transaction","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsignedTransactionResponse"}}}},"400":{"description":"Build error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Token identity mismatch","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}}}}},"/v1/spl/undelegate-ephemeral-ata":{"post":{"tags":["SPL"],"description":"Build an unsigned ephemeral-rollup transaction that undelegates a wallet eATA for a mint.","parameters":[{"schema":{"type":"string","example":"Bearer 1234567890","description":"Optional. Authentication token for requests that need to connect to the Private Ephemeral Rollup."},"required":false,"description":"Optional. Authentication token for requests that need to connect to the Private Ephemeral Rollup.","name":"authorization","in":"header"}],"requestBody":{"required":true,"description":"Undelegate eATA request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UndelegateEphemeralAtaRequest"}}}},"responses":{"200":{"description":"Unsigned serialized transaction","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UndelegateEphemeralAtaResponse"},"example":{"kind":"undelegateEphemeralAta","version":"legacy","transactionBase64":"AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAAIDKmcfsS5XfSOLaLlaBHJry50iH2Ufk2TMz4STC2fHzIcFKkerg3q2DD3Yn8TISmGeKoxSLz+BiP7iQ4pYqXYXsgu8D8C7R8ovdMQRLpSrE8+jxjTl3BfqywPNGiPNfnh8AazZ0ixOauLjpxaRgDCv6MChaoMAZAJg8BnPbZl31jECAgEBBAECAwQCAQEEAgIDBA==","sendTo":"ephemeral","sendRpcEndpoint":"https://devnet-tee.magicblock.app","recentBlockhash":"7YH7nE6qj8vH3L9pR5uM2cD1xK4sT8wQ6bN3fJ2mP9z","lastValidBlockHeight":284512451,"instructionCount":1,"requiredSigners":["3rXKwQ1kpjBd5tdcco32qsvqUh1BnZjcYnS5kYrP7AYE"]}}}},"400":{"description":"Build error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Token identity mismatch","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}}}}},"/v1/spl/stealth-pool":{"post":{"tags":["SPL"],"description":"Build unsigned stealth-pool setup and ER update transactions.","parameters":[{"schema":{"type":"string","example":"Bearer 1234567890","description":"Required. Authentication token for private-balance requests."},"required":true,"description":"Required. Authentication token for private-balance requests.","name":"authorization","in":"header"}],"requestBody":{"required":true,"description":"Stealth pool request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StealthPoolRequest"}}}},"responses":{"200":{"description":"Unsigned serialized transaction","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StealthPoolResponse"},"example":{"kind":"stealthPool","version":"legacy","transactionBase64":"AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAAIDKmcfsS5XfSOLaLlaBHJry50iH2Ufk2TMz4STC2fHzIcFKkerg3q2DD3Yn8TISmGeKoxSLz+BiP7iQ4pYqXYXsgu8D8C7R8ovdMQRLpSrE8+jxjTl3BfqywPNGiPNfnh8eS+smowIxqKDcCjw5liNXQkkCbBSDCBDFwtrgCKqoQ0DAgEBBAECAwQCAQEEAgIDBAIBAQQDAgME","sendTo":"ephemeral","recentBlockhash":"9A4VhP8M8fQZxP4h7rB6mP6eM8w2pJkYh7QdZk7V4r2x","lastValidBlockHeight":284512337,"instructionCount":1,"requiredSigners":["3rXKwQ1kpjBd5tdcco32qsvqUh1BnZjcYnS5kYrP7AYE"],"setupTransaction":{"kind":"stealthPool","version":"legacy","transactionBase64":"AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAAIDKgcfsS5XfSOLaLlaBHJry50iH2Ufk2TMz4STC2fHzIcFKkerg3q2DD3Yn8TISmGeKoxSLz+BiP7iQ4pYqXYXsgu8D8C7R8ovdMQRLpSrE8+jxjTl3BfqywPNGiPNfnh8eS+smowIxqKDcCjw5liNXQkkCbBSDCBDFwtrgCKqoQ0DAgEBBAECAwQCAQEEAgIDBAIBAQQDAgME","sendTo":"base","recentBlockhash":"7YH7nE6qj8vH3L9pR5uM2cD1xK4sT8wQ6bN3fJ2mP9z","lastValidBlockHeight":284512451,"instructionCount":1,"requiredSigners":["3rXKwQ1kpjBd5tdcco32qsvqUh1BnZjcYnS5kYrP7AYE"],"validator":"MAS1Dt9qreoRMQ14YQuhg8UTZMMzDdKhmkZMECCzk57"},"stealthPool":"Bt9oNR5cCtnfuMmXgWELd6q5i974PdEMQDUE55nBC57L"}}}},"400":{"description":"Build error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}}}},"get":{"tags":["SPL"],"description":"Derive a stealth pool PDA from an exact handle and report whether the base account exists.","parameters":[{"schema":{"type":"string","minLength":1,"example":"john.doe@magicblock.id","description":"Exact canonical handle string, up to 255 UTF-8 bytes. The API derives the stealth-pool PDA from these UTF-8 bytes as-is; it does not trim, lowercase, or normalize."},"required":true,"description":"Exact canonical handle string, up to 255 UTF-8 bytes. The API derives the stealth-pool PDA from these UTF-8 bytes as-is; it does not trim, lowercase, or normalize.","name":"handle","in":"query"},{"schema":{"anyOf":[{"type":"string","enum":["mainnet","devnet","mainnet-private","devnet-private"]},{"type":"string","format":"uri"}],"example":"mainnet","description":"Optional, defaults to `mainnet`. `mainnet` and `devnet` route to the public ephemeral RPC for that network; `mainnet-private` and `devnet-private` route to the TEE-backed Private Ephemeral Rollup and are required for auth and bearer-token-gated reads. A custom http(s) RPC URL overrides only the base RPC while keeping the configured ephemeral RPC."},"required":false,"description":"Optional, defaults to `mainnet`. `mainnet` and `devnet` route to the public ephemeral RPC for that network; `mainnet-private` and `devnet-private` route to the TEE-backed Private Ephemeral Rollup and are required for auth and bearer-token-gated reads. A custom http(s) RPC URL overrides only the base RPC while keeping the configured ephemeral RPC.","name":"cluster","in":"query"}],"responses":{"200":{"description":"Stealth pool status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StealthPoolStatusResponse"}}}},"400":{"description":"Query error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}}}}},"/v1/spl/balance":{"get":{"tags":["SPL"],"description":"Get the balance for the owner's ATA on the base RPC, along with the delegation state of the owner's eATA (delegated validator identity, and the ephemeral endpoint when statically known).","parameters":[{"schema":{"type":"string","example":"So11111111111111111111111111111111111111112"},"required":true,"name":"address","in":"query"},{"schema":{"type":"string","example":"So11111111111111111111111111111111111111112"},"required":true,"name":"mint","in":"query"},{"schema":{"anyOf":[{"type":"string","enum":["mainnet","devnet","mainnet-private","devnet-private"]},{"type":"string","format":"uri"}],"example":"mainnet","description":"Optional, defaults to `mainnet`. `mainnet` and `devnet` route to the public ephemeral RPC for that network; `mainnet-private` and `devnet-private` route to the TEE-backed Private Ephemeral Rollup and are required for auth and bearer-token-gated reads. A custom http(s) RPC URL overrides only the base RPC while keeping the configured ephemeral RPC."},"required":false,"description":"Optional, defaults to `mainnet`. `mainnet` and `devnet` route to the public ephemeral RPC for that network; `mainnet-private` and `devnet-private` route to the TEE-backed Private Ephemeral Rollup and are required for auth and bearer-token-gated reads. A custom http(s) RPC URL overrides only the base RPC while keeping the configured ephemeral RPC.","name":"cluster","in":"query"}],"responses":{"200":{"description":"Base-chain token balance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BalanceResponse"},"example":{"address":"Bt9oNR5cCtnfuMmXgWELd6q5i974PdEMQDUE55nBC57L","mint":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","ata":"3rXKwQ1kpjBd5tdcco32qsvqUh1BnZjcYnS5kYrP7AYE","location":"base","balance":"1000000","delegation":{"status":"delegated","validator":"MAS1Dt9qreoRMQ14YQuhg8UTZMMzDdKhmkZMECCzk57"}}}}},"400":{"description":"Query error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}}}}},"/v1/spl/private-balance":{"get":{"tags":["SPL"],"description":"Get the owner's private balance when the eATA is delegated to the selected ephemeral RPC.","parameters":[{"schema":{"type":"string","example":"So11111111111111111111111111111111111111112"},"required":true,"name":"address","in":"query"},{"schema":{"type":"string","example":"So11111111111111111111111111111111111111112"},"required":true,"name":"mint","in":"query"},{"schema":{"anyOf":[{"type":"string","enum":["mainnet","devnet","mainnet-private","devnet-private"]},{"type":"string","format":"uri"}],"example":"mainnet","description":"Optional, defaults to `mainnet`. `mainnet` and `devnet` route to the public ephemeral RPC for that network; `mainnet-private` and `devnet-private` route to the TEE-backed Private Ephemeral Rollup and are required for auth and bearer-token-gated reads. A custom http(s) RPC URL overrides only the base RPC while keeping the configured ephemeral RPC."},"required":false,"description":"Optional, defaults to `mainnet`. `mainnet` and `devnet` route to the public ephemeral RPC for that network; `mainnet-private` and `devnet-private` route to the TEE-backed Private Ephemeral Rollup and are required for auth and bearer-token-gated reads. A custom http(s) RPC URL overrides only the base RPC while keeping the configured ephemeral RPC.","name":"cluster","in":"query"},{"schema":{"type":"string","example":"Bearer 1234567890","description":"Required. Authentication token for private-balance requests."},"required":true,"description":"Required. Authentication token for private-balance requests.","name":"authorization","in":"header"}],"responses":{"200":{"description":"Ephemeral token balance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BalanceResponse"},"example":{"address":"Bt9oNR5cCtnfuMmXgWELd6q5i974PdEMQDUE55nBC57L","mint":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","ata":"3rXKwQ1kpjBd5tdcco32qsvqUh1BnZjcYnS5kYrP7AYE","location":"ephemeral","balance":"1000000","delegation":{"status":"delegated","validator":"MAS1Dt9qreoRMQ14YQuhg8UTZMMzDdKhmkZMECCzk57"}}}}},"400":{"description":"Query error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Token identity mismatch","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}}}}},"/v1/spl/is-mint-initialized":{"get":{"tags":["SPL"],"description":"Check whether the validator-scoped transfer queue exists for a mint on the ephemeral RPC.","parameters":[{"schema":{"type":"string","example":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"},"required":true,"name":"mint","in":"query"},{"schema":{"anyOf":[{"type":"string","enum":["mainnet","devnet","mainnet-private","devnet-private"]},{"type":"string","format":"uri"}],"example":"mainnet","description":"Optional, defaults to `mainnet`. `mainnet` and `devnet` route to the public ephemeral RPC for that network; `mainnet-private` and `devnet-private` route to the TEE-backed Private Ephemeral Rollup and are required for auth and bearer-token-gated reads. A custom http(s) RPC URL overrides only the base RPC while keeping the configured ephemeral RPC."},"required":false,"description":"Optional, defaults to `mainnet`. `mainnet` and `devnet` route to the public ephemeral RPC for that network; `mainnet-private` and `devnet-private` route to the TEE-backed Private Ephemeral Rollup and are required for auth and bearer-token-gated reads. A custom http(s) RPC URL overrides only the base RPC while keeping the configured ephemeral RPC.","name":"cluster","in":"query"},{"schema":{"type":"string","example":"MAS1Dt9qreoRMQ14YQuhg8UTZMMzDdKhmkZMECCzk57","description":"Optional. Defaults to the selected ephemeral RPC identity resolved via `getIdentity`."},"required":false,"description":"Optional. Defaults to the selected ephemeral RPC identity resolved via `getIdentity`.","name":"validator","in":"query"}],"responses":{"200":{"description":"Mint transfer queue initialization status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MintInitializationResponse"},"example":{"mint":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","validator":"MAS1Dt9qreoRMQ14YQuhg8UTZMMzDdKhmkZMECCzk57","transferQueue":"BuBHLbaPmYmgvMiZ8uZb96RjBtmWzJY52u7Di5urNf6M","initialized":true}}}},"400":{"description":"Query error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}}}}},"/v1/spl/transfer-queue/ensure-crank":{"post":{"tags":["SPL"],"description":"After setup confirmation, verify the validator-scoped transfer queue and force one crank attempt.","requestBody":{"required":true,"description":"Transfer queue crank request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransferQueueEnsureCrankRequest"}}}},"responses":{"200":{"description":"Forced transfer queue crank result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransferQueueEnsureCrankResponse"},"example":{"mint":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","validator":"MAS1Dt9qreoRMQ14YQuhg8UTZMMzDdKhmkZMECCzk57","transferQueue":"BuBHLbaPmYmgvMiZ8uZb96RjBtmWzJY52u7Di5urNf6M","crankSignature":"5XwJvR8L5cYk2wA9yEq2Ur2VXn7zqftzZa8cqBgrQYorZxeFaNRDnQsf3tGYRjB3sxG9DhU6N2qWctvd8vG82yXQ"}}}},"400":{"description":"Crank error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}}}}},"/v1/spl/challenge":{"get":{"tags":["SPL"],"description":"Generate a challenge string for the wallet to sign. Requires `cluster=mainnet-private` or `cluster=devnet-private`; the auth service runs on the TEE validators only.","parameters":[{"schema":{"anyOf":[{"type":"string","enum":["mainnet","devnet","mainnet-private","devnet-private"]},{"type":"string","format":"uri"}],"example":"mainnet","description":"Optional, defaults to `mainnet`. `mainnet` and `devnet` route to the public ephemeral RPC for that network; `mainnet-private` and `devnet-private` route to the TEE-backed Private Ephemeral Rollup and are required for auth and bearer-token-gated reads. A custom http(s) RPC URL overrides only the base RPC while keeping the configured ephemeral RPC."},"required":false,"description":"Optional, defaults to `mainnet`. `mainnet` and `devnet` route to the public ephemeral RPC for that network; `mainnet-private` and `devnet-private` route to the TEE-backed Private Ephemeral Rollup and are required for auth and bearer-token-gated reads. A custom http(s) RPC URL overrides only the base RPC while keeping the configured ephemeral RPC.","name":"cluster","in":"query"},{"schema":{"type":"string","example":"Bt9oNR5cCtnfuMmXgWELd6q5i974PdEMQDUE55nBC57L","description":"The public key of the wallet that will read private data"},"required":true,"description":"The public key of the wallet that will read private data","name":"pubkey","in":"query"}],"responses":{"200":{"description":"Challenge string","content":{"application/json":{"schema":{"type":"object","properties":{"challenge":{"type":"string","example":"1234567890","description":"The challenge string generated by the Private Ephemeral Rollup"},"error":{"type":"string"}},"required":["challenge"]},"example":{"challenge":"1234567890"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/spl/login":{"post":{"tags":["SPL"],"description":"Login the wallet to the Private Ephemeral Rollup. Exchanges the signed challenge from `/v1/spl/challenge` for a bearer token. Use the same `-private` cluster as the challenge request.","requestBody":{"required":true,"description":"Login request","content":{"application/json":{"schema":{"type":"object","properties":{"cluster":{"anyOf":[{"type":"string","enum":["mainnet","devnet","mainnet-private","devnet-private"]},{"type":"string","format":"uri"}],"example":"mainnet","description":"Optional, defaults to `mainnet`. `mainnet` and `devnet` route to the public ephemeral RPC for that network; `mainnet-private` and `devnet-private` route to the TEE-backed Private Ephemeral Rollup and are required for auth and bearer-token-gated reads. A custom http(s) RPC URL overrides only the base RPC while keeping the configured ephemeral RPC."},"pubkey":{"type":"string","example":"Bt9oNR5cCtnfuMmXgWELd6q5i974PdEMQDUE55nBC57L","description":"The public key of the wallet that will read private data"},"challenge":{"type":"string","example":"1234567890","description":"The challenge string generated by the Private Ephemeral Rollup"},"signature":{"type":"string","example":"1234567890","description":"The signature of the challenge by the wallet"}},"required":["pubkey","challenge","signature"]}}}},"responses":{"200":{"description":"Login response","content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","example":"1234567890","description":"The authentication token provided by the Private Ephemeral Rollup"},"error":{"type":"string"}},"required":["token"]},"example":{"token":"1234567890"}}}},"403":{"description":"Signature verification failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/swap/quote":{"get":{"tags":["Swap"],"description":"Get a swap quote.","parameters":[{"schema":{"type":"string","example":"So11111111111111111111111111111111111111112","description":"Input token mint address."},"required":true,"description":"Input token mint address.","name":"inputMint","in":"query"},{"schema":{"type":"string","example":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","description":"Output token mint address."},"required":true,"description":"Output token mint address.","name":"outputMint","in":"query"},{"schema":{"type":"string","pattern":"^\\d+$","example":"1000000","description":"Raw amount to swap before decimals are applied."},"required":true,"description":"Raw amount to swap before decimals are applied.","name":"amount","in":"query"},{"schema":{"type":"integer","minimum":0,"example":50,"description":"Slippage threshold in basis points."},"required":false,"description":"Slippage threshold in basis points.","name":"slippageBps","in":"query"},{"schema":{"allOf":[{"$ref":"#/components/schemas/SwapMode"},{"example":"ExactIn","description":"Use `ExactIn` for fixed input amount or `ExactOut` for fixed output amount."}]},"required":false,"description":"Use `ExactIn` for fixed input amount or `ExactOut` for fixed output amount.","name":"swapMode","in":"query"},{"schema":{"type":"string","example":"Raydium,Orca+V2","description":"Optional comma-separated list of DEX labels to include."},"required":false,"description":"Optional comma-separated list of DEX labels to include.","name":"dexes","in":"query"},{"schema":{"type":"string","example":"Meteora+DLMM","description":"Optional comma-separated list of DEX labels to exclude."},"required":false,"description":"Optional comma-separated list of DEX labels to exclude.","name":"excludeDexes","in":"query"},{"schema":{"type":"boolean","example":true,"description":"Restrict intermediate tokens to a more stable set."},"required":false,"description":"Restrict intermediate tokens to a more stable set.","name":"restrictIntermediateTokens","in":"query"},{"schema":{"type":"boolean","example":false,"description":"Limit routing to a single hop."},"required":false,"description":"Limit routing to a single hop.","name":"onlyDirectRoutes","in":"query"},{"schema":{"type":"boolean","example":false,"description":"Request a legacy transaction-compatible route."},"required":false,"description":"Request a legacy transaction-compatible route.","name":"asLegacyTransaction","in":"query"},{"schema":{"type":"integer","minimum":0,"example":20,"description":"Optional platform fee in basis points."},"required":false,"description":"Optional platform fee in basis points.","name":"platformFeeBps","in":"query"},{"schema":{"type":"integer","minimum":0,"example":64,"description":"Approximate maximum account budget for the route."},"required":false,"description":"Approximate maximum account budget for the route.","name":"maxAccounts","in":"query"},{"schema":{"allOf":[{"$ref":"#/components/schemas/InstructionVersion"},{"example":"V1","description":"Instruction format to target."}]},"required":false,"description":"Instruction format to target.","name":"instructionVersion","in":"query"},{"schema":{"type":"boolean","example":false,"description":"Keep for compatibility with upstream quote parameters."},"required":false,"description":"Keep for compatibility with upstream quote parameters.","name":"dynamicSlippage","in":"query"},{"schema":{"type":"boolean","example":false,"description":"Exclude routes that are incompatible with Jito bundles."},"required":false,"description":"Exclude routes that are incompatible with Jito bundles.","name":"forJitoBundle","in":"query"},{"schema":{"type":"boolean","example":false,"description":"Allow dynamic selection of intermediate tokens."},"required":false,"description":"Allow dynamic selection of intermediate tokens.","name":"supportDynamicIntermediateTokens","in":"query"}],"responses":{"200":{"description":"Swap quote","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SwapQuoteResponse"},"example":{"inputMint":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","inAmount":"1000000","outputMint":"Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB","outAmount":"999519","otherAmountThreshold":"994522","swapMode":"ExactIn","slippageBps":50,"platformFee":null,"priceImpactPct":"0","routePlan":[{"swapInfo":{"ammKey":"DB3sUCP2H4icbeKmK6yb6nUxU5ogbcRHtGuq7W2RoRwW","label":"HumidiFi","inputMint":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","outputMint":"So11111111111111111111111111111111111111112","inAmount":"1000000","outAmount":"11687625","updateContextSlot":"414697032"},"percent":100,"bps":null},{"swapInfo":{"ammKey":"4rJggoVMajEUtipev1XhSMjESYk8Zibz6CDHPtUe1mem","label":"GoonFi V2","inputMint":"So11111111111111111111111111111111111111112","outputMint":"Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB","inAmount":"11687625","outAmount":"999519","updateContextSlot":"414697032"},"percent":100,"bps":null}],"contextSlot":414697033,"timeTaken":0.001218002,"swapUsdValue":"1","mostReliableAmmsQuoteReport":{"info":{"BZtgQEyS6eXUXicYPHecYQ7PybqodXQMvkjUbP4R8mUU":"999357","Czfq3xZZDmsdGdUyrNLtRhGc47cXcZtLG4crryfu44zE":"11681475","8sjV1AqBFvFuADBCQHhotaRq5DFFYSjjg1jMyVWMqXvZ":"999504"}},"longtailMarketQuoteReport":null,"useIncurredSlippageForQuoting":null,"useRewards":null,"otherRoutePlans":null,"loadedLongtailToken":false,"instructionVersion":null}}}},"500":{"description":"Configuration error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Upstream error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/swap/swap":{"post":{"tags":["Swap"],"description":"Build an unsigned swap transaction from a quote.\n\nSupports two visibility modes:\n\n- **`visibility: \"public\"`** (default) — pure pass-through to the Jupiter/Metis\n  upstream. The returned transaction is whatever the upstream produces.\n- **`visibility: \"private\"`** — the server forces Jupiter's output into a\n  program-owned stash ATA (deterministically derived from `(userPublicKey,\n  quoteResponse.outputMint)`), prepends an idempotent ATA-create, and appends a\n  `schedule_private_transfer` instruction that registers a one-shot Hydra\n  crank. When the crank fires, it self-CPIs into the on-chain private-transfer\n  flow to deliver the swapped tokens to `destination` with the requested\n  delay/split policy. The returned transaction is a v0 `VersionedTransaction`\n  that is still unsigned — the client signs and submits.\n\nWhen `visibility = \"private\"`, the fields `destination`, `minDelayMs`,\n`maxDelayMs`, and `split` are **required**. `clientRefId` and `validator` are\noptional. Explicitly setting `destinationTokenAccount` to anything other than\nthe server-derived stash ATA returns 400.","requestBody":{"required":true,"description":"Swap request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SwapRequest"},"examples":{"private":{"summary":"Private swap + scheduled transfer","description":"Forces Jupiter's output into the program-owned stash ATA and appends schedule_private_transfer.","value":{"userPublicKey":"3rXKwQ1kpjBd5tdcco32qsvqUh1BnZjcYnS5kYrP7AYE","quoteResponse":{"inputMint":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","inAmount":"1000000","outputMint":"Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB","outAmount":"999519","otherAmountThreshold":"994522","swapMode":"ExactIn","slippageBps":50,"platformFee":null,"priceImpactPct":"0","routePlan":[{"swapInfo":{"ammKey":"DB3sUCP2H4icbeKmK6yb6nUxU5ogbcRHtGuq7W2RoRwW","label":"HumidiFi","inputMint":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","outputMint":"So11111111111111111111111111111111111111112","inAmount":"1000000","outAmount":"11687625","updateContextSlot":"414697032"},"percent":100,"bps":null},{"swapInfo":{"ammKey":"4rJggoVMajEUtipev1XhSMjESYk8Zibz6CDHPtUe1mem","label":"GoonFi V2","inputMint":"So11111111111111111111111111111111111111112","outputMint":"Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB","inAmount":"11687625","outAmount":"999519","updateContextSlot":"414697032"},"percent":100,"bps":null}],"contextSlot":414697033,"timeTaken":0.001218002,"swapUsdValue":"1","mostReliableAmmsQuoteReport":{"info":{"BZtgQEyS6eXUXicYPHecYQ7PybqodXQMvkjUbP4R8mUU":"999357","Czfq3xZZDmsdGdUyrNLtRhGc47cXcZtLG4crryfu44zE":"11681475","8sjV1AqBFvFuADBCQHhotaRq5DFFYSjjg1jMyVWMqXvZ":"999504"}},"longtailMarketQuoteReport":null,"useIncurredSlippageForQuoting":null,"useRewards":null,"otherRoutePlans":null,"loadedLongtailToken":false,"instructionVersion":null},"visibility":"private","destination":"7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU","minDelayMs":"0","maxDelayMs":"0","split":1}},"public":{"summary":"Public swap (default behaviour, upstream proxy)","value":{"userPublicKey":"3rXKwQ1kpjBd5tdcco32qsvqUh1BnZjcYnS5kYrP7AYE","quoteResponse":{"inputMint":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","inAmount":"1000000","outputMint":"Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB","outAmount":"999519","otherAmountThreshold":"994522","swapMode":"ExactIn","slippageBps":50,"platformFee":null,"priceImpactPct":"0","routePlan":[{"swapInfo":{"ammKey":"DB3sUCP2H4icbeKmK6yb6nUxU5ogbcRHtGuq7W2RoRwW","label":"HumidiFi","inputMint":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","outputMint":"So11111111111111111111111111111111111111112","inAmount":"1000000","outAmount":"11687625","updateContextSlot":"414697032"},"percent":100,"bps":null},{"swapInfo":{"ammKey":"4rJggoVMajEUtipev1XhSMjESYk8Zibz6CDHPtUe1mem","label":"GoonFi V2","inputMint":"So11111111111111111111111111111111111111112","outputMint":"Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB","inAmount":"11687625","outAmount":"999519","updateContextSlot":"414697032"},"percent":100,"bps":null}],"contextSlot":414697033,"timeTaken":0.001218002,"swapUsdValue":"1","mostReliableAmmsQuoteReport":{"info":{"BZtgQEyS6eXUXicYPHecYQ7PybqodXQMvkjUbP4R8mUU":"999357","Czfq3xZZDmsdGdUyrNLtRhGc47cXcZtLG4crryfu44zE":"11681475","8sjV1AqBFvFuADBCQHhotaRq5DFFYSjjg1jMyVWMqXvZ":"999504"}},"longtailMarketQuoteReport":null,"useIncurredSlippageForQuoting":null,"useRewards":null,"otherRoutePlans":null,"loadedLongtailToken":false,"instructionVersion":null}}}}}}},"responses":{"200":{"description":"Swap transaction","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SwapResponse"},"examples":{"private":{"summary":"Response for visibility=private (with diagnostic block)","value":{"swapTransaction":"AQABA...base64 with appended ATA-create + schedule_private_transfer...","lastValidBlockHeight":318120000,"privateTransfer":{"stashAta":"9mZP3xKHvVqXd3xtk72nSeEwJjmsgqmXvUDfwNA9BM4K","hydraCrankPda":"HyDraCrNkPdA11111111111111111111111111111111","shuttleId":2147483647}}},"public":{"summary":"Response for visibility=public","value":{"swapTransaction":"AQABA...base64...","lastValidBlockHeight":318120000}}}}}},"400":{"description":"Invalid request (missing or conflicting private-transfer fields)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Configuration error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Upstream error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/transaction/send":{"post":{"tags":["Transaction"],"description":"Submit a signed serialized transaction to the base or ephemeral RPC selected by `sendTo`.","parameters":[{"schema":{"type":"string","example":"Bearer 1234567890","description":"Optional. Authentication token for requests that need to connect to the Private Ephemeral Rollup."},"required":false,"description":"Optional. Authentication token for requests that need to connect to the Private Ephemeral Rollup.","name":"authorization","in":"header"}],"requestBody":{"required":true,"description":"Send transaction request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendTransactionRequest"},"example":{"transactionBase64":"AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAA==","sendTo":"base"}}}},"responses":{"200":{"description":"Submitted transaction","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendTransactionResponse"},"example":{"signature":"5Nf6YwU8z2Y4QyQZ9pQ6xT2P7mK3sV4nY8rD1hJ5kL9m","sendTo":"base","confirmed":false,"confirmationRpcEndpoint":"https://api.mainnet-beta.solana.com","confirmationRequiresAuthToken":false}}}},"400":{"description":"Send error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"502":{"description":"RPC error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/mcp":{"post":{"tags":["MCP"],"description":"Stateless Streamable HTTP MCP endpoint.\n\nImplementation details:\n- Each `POST /mcp` request creates a fresh `McpServer`, handles the JSON-RPC exchange, then closes it.\n- The transport runs with `sessionIdGenerator: undefined` and `enableJsonResponse: true`, so this server does not issue or require `mcp-session-id` headers.\n- `GET /mcp` returns the info document and `GET /.well-known/mcp.json` returns the discovery document.\n- Clients can use `Accept: application/json` with `Content-Type: application/json`.\n\nTypical flow:\n1. `initialize`\n2. `notifications/initialized`\n3. `tools/list` or `tools/call`\n\nInitialize request example:\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 1,\n  \"method\": \"initialize\",\n  \"params\": {\n    \"protocolVersion\": \"2025-11-25\",\n    \"capabilities\": {},\n    \"clientInfo\": {\n      \"name\": \"curl-example\",\n      \"version\": \"1.0.0\"\n    }\n  }\n}\n```\n\nInitialize response example:\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 1,\n  \"result\": {\n    \"protocolVersion\": \"2025-11-25\",\n    \"capabilities\": {\n      \"tools\": {\n        \"listChanged\": true\n      }\n    },\n    \"serverInfo\": {\n      \"name\": \"spl-private-payments-api\",\n      \"version\": \"0.1.0\"\n    }\n  }\n}\n```\n\nTool call request example:\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 3,\n  \"method\": \"tools/call\",\n  \"params\": {\n    \"name\": \"spl.deposit\",\n    \"arguments\": {\n      \"owner\": \"3rXKwQ1kpjBd5tdcco32qsvqUh1BnZjcYnS5kYrP7AYE\",\n      \"amount\": 1,\n      \"initIfMissing\": true,\n      \"initAtasIfMissing\": true,\n      \"initVaultIfMissing\": false,\n      \"idempotent\": true,\n      \"private\": true\n    }\n  }\n}\n```","responses":{"200":{"description":"MCP JSON-RPC response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpResponse"},"example":{"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"Built an unsigned SPL deposit transaction."}],"structuredContent":{"kind":"deposit","version":"legacy","transactionBase64":"AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAAIDKmcfsS5XfSOLaLlaBHJry50iH2Ufk2TMz4STC2fHzIcFKkerg3q2DD3Yn8TISmGeKoxSLz+BiP7iQ4pYqXYXsgu8D8C7R8ovdMQRLpSrE8+jxjTl3BfqywPNGiPNfnh8eS+smowIxqKDcCjw5liNXQkkCbBSDCBDFwtrgCKqoQ0DAgEBBAECAwQCAQEEAgIDBAIBAQQDAgME","sendTo":"base","recentBlockhash":"9A4VhP8M8fQZxP4h7rB6mP6eM8w2pJkYh7QdZk7V4r2x","lastValidBlockHeight":284512337,"instructionCount":3,"requiredSigners":["3rXKwQ1kpjBd5tdcco32qsvqUh1BnZjcYnS5kYrP7AYE"],"validator":"MAS1Dt9qreoRMQ14YQuhg8UTZMMzDdKhmkZMECCzk57"}}}}}},"202":{"description":"Notification accepted; no response body is returned."},"400":{"description":"Invalid JSON or invalid JSON-RPC request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpResponse"},"example":{"jsonrpc":"2.0","error":{"code":-32700,"message":"Parse error"},"id":null}}}},"415":{"description":"Content-Type must be application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpResponse"},"example":{"jsonrpc":"2.0","error":{"code":-32000,"message":"Unsupported Media Type: Content-Type must be application/json"},"id":null}}}},"500":{"description":"MCP JSON-RPC error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpResponse"},"example":{"jsonrpc":"2.0","error":{"code":-32603,"message":"Internal server error"},"id":null}}}}},"requestBody":{"required":true,"description":"MCP JSON-RPC request","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"id":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"null"}]},"method":{"type":"string"},"params":{}},"required":["jsonrpc","method"]},"example":{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl-example","version":"1.0.0"}}}}}}}},"/v1/merchants/challenge":{"post":{"tags":["Payments"],"summary":"Request a wallet-signed merchant registration or key-rotation challenge","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"wallet":{"type":"string","example":"So11111111111111111111111111111111111111112"},"purpose":{"type":"string","enum":["register","rotate-key"],"default":"register"}},"required":["wallet"],"additionalProperties":false}}}},"responses":{"200":{"description":"Payment API response","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"202":{"description":"Payment pending; retry status without creating another charge","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Order conflict or failed payment","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"503":{"description":"Payments unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/merchants":{"post":{"tags":["Payments"],"summary":"Register a merchant; signature is base64 Ed25519 over the exact challenge message","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"wallet":{"type":"string","example":"So11111111111111111111111111111111111111112"},"challengeId":{"type":"string","format":"uuid"},"signature":{"type":"string","minLength":88,"maxLength":88}},"required":["wallet","challengeId","signature"],"additionalProperties":false}}}},"responses":{"200":{"description":"Payment API response","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"202":{"description":"Payment pending; retry status without creating another charge","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Order conflict or failed payment","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"503":{"description":"Payments unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/merchants/rotate-key":{"post":{"tags":["Payments"],"summary":"Rotate a merchant API key using a fresh wallet-signed rotate-key challenge","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"wallet":{"type":"string","example":"So11111111111111111111111111111111111111112"},"challengeId":{"type":"string","format":"uuid"},"signature":{"type":"string","minLength":88,"maxLength":88}},"required":["wallet","challengeId","signature"],"additionalProperties":false}}}},"responses":{"200":{"description":"Payment API response","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"202":{"description":"Payment pending; retry status without creating another charge","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Order conflict or failed payment","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"503":{"description":"Payments unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/payments":{"post":{"tags":["Payments"],"summary":"Create a checkout; externalReference is unique per merchant and retries return the same payment","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string","pattern":"^[1-9][0-9]{0,19}$"},"cluster":{"type":"string","enum":["mainnet","devnet","mainnet-private","devnet-private"],"default":"mainnet-private","description":"Defaults to the configured mainnet TEE for public or private accounts. Account permissions determine privacy; public validators do not preserve it."},"description":{"type":"string","minLength":1,"maxLength":256},"resource":{"type":"string","maxLength":2048,"format":"uri"},"requestHash":{"type":"string","pattern":"^[a-f0-9]{64}$"},"expiresInSeconds":{"type":"integer","minimum":60,"maximum":86400,"default":3600},"payer":{"type":"string","example":"So11111111111111111111111111111111111111112"},"externalReference":{"type":"string","minLength":1,"maxLength":128}},"required":["amount","payer","externalReference"],"additionalProperties":false}}}},"responses":{"200":{"description":"Payment API response","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"202":{"description":"Payment pending; retry status without creating another charge","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Order conflict or failed payment","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"503":{"description":"Payments unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/payment-links":{"post":{"tags":["Payments"],"summary":"Create a reusable offer; checkout sessions are created separately for each buyer","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string","pattern":"^[1-9][0-9]{0,19}$"},"cluster":{"type":"string","enum":["mainnet","devnet","mainnet-private","devnet-private"],"default":"mainnet-private","description":"Defaults to the configured mainnet TEE for public or private accounts. Account permissions determine privacy; public validators do not preserve it."},"description":{"type":"string","minLength":1,"maxLength":256},"resource":{"type":"string","maxLength":2048,"format":"uri"},"requestHash":{"type":"string","pattern":"^[a-f0-9]{64}$"},"expiresInSeconds":{"type":"integer","minimum":60,"maximum":86400,"default":3600},"externalReference":{"type":"string","minLength":1,"maxLength":128}},"required":["amount","externalReference"],"additionalProperties":false}}}},"responses":{"200":{"description":"Payment API response","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"202":{"description":"Payment pending; retry status without creating another charge","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Order conflict or failed payment","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"503":{"description":"Payments unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/payment-links/{merchantId}/{linkId}":{"get":{"tags":["Payments"],"summary":"Read a public offer; does not reveal buyer or payment status","parameters":[{"schema":{"type":"string","example":"So11111111111111111111111111111111111111112"},"required":true,"name":"merchantId","in":"path"},{"schema":{"type":"string","pattern":"^[a-f0-9]{64}$"},"required":true,"name":"linkId","in":"path"}],"responses":{"200":{"description":"Payment API response","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"202":{"description":"Payment pending; retry status without creating another charge","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Order conflict or failed payment","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"503":{"description":"Payments unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/payment-links/{merchantId}/{linkId}/checkouts":{"post":{"tags":["Payments"],"summary":"Create a buyer checkout; keep the random UUIDv4 Idempotency-Key secret for recovery","parameters":[{"schema":{"type":"string","example":"So11111111111111111111111111111111111111112"},"required":true,"name":"merchantId","in":"path"},{"schema":{"type":"string","pattern":"^[a-f0-9]{64}$"},"required":true,"name":"linkId","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"payer":{"type":"string","example":"So11111111111111111111111111111111111111112"}},"required":["payer"],"additionalProperties":false}}}},"responses":{"200":{"description":"Payment API response","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"202":{"description":"Payment pending; retry status without creating another charge","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Order conflict or failed payment","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"503":{"description":"Payments unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/payments/{id}":{"get":{"tags":["Payments"],"summary":"Read/reconcile a payment using its merchant key or checkout access token","parameters":[{"schema":{"type":"string","pattern":"^[a-f0-9]{64}$"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Payment API response","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"202":{"description":"Payment pending; retry status without creating another charge","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Order conflict or failed payment","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"503":{"description":"Payments unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/payments/{id}/prepare":{"post":{"tags":["Payments"],"summary":"Prepare one fee-free ER transfer for signing; the prepared message is immutable","parameters":[{"schema":{"type":"string","pattern":"^[a-f0-9]{64}$"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Payment API response","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"202":{"description":"Payment pending; retry status without creating another charge","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Order conflict or failed payment","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"503":{"description":"Payments unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/payments/{id}/settle":{"post":{"tags":["Payments"],"summary":"Submit an exact signed payment; pending responses are not proof of payment","parameters":[{"schema":{"type":"string","pattern":"^[a-f0-9]{64}$"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"transactionBase64":{"type":"string","minLength":1,"maxLength":1644}},"required":["transactionBase64"],"additionalProperties":false}}}},"responses":{"200":{"description":"Payment API response","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"202":{"description":"Payment pending; retry status without creating another charge","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Order conflict or failed payment","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"503":{"description":"Payments unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/x402/payments/{id}/pay":{"post":{"tags":["x402"],"summary":"x402 checkout: get a challenge, then retry with PAYMENT-SIGNATURE","parameters":[{"schema":{"type":"string","pattern":"^[a-f0-9]{64}$"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Payment API response","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"202":{"description":"Payment pending; retry status without creating another charge","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"x402 payment required; see PAYMENT-REQUIRED","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"409":{"description":"Order conflict or failed payment","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"503":{"description":"Payments unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/x402/supported":{"get":{"tags":["x402"],"summary":"Supported custom MagicBlock payment schemes","responses":{"200":{"description":"Payment API response","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"202":{"description":"Payment pending; retry status without creating another charge","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Order conflict or failed payment","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"503":{"description":"Payments unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/x402/verify":{"post":{"tags":["x402"],"summary":"x402 facilitator verify; requires merchant API credentials","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"x402Version":{"type":"number","enum":[2]},"paymentPayload":{},"paymentRequirements":{}},"required":["x402Version"],"additionalProperties":false}}}},"responses":{"200":{"description":"Payment API response","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"202":{"description":"Payment pending; retry status without creating another charge","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Order conflict or failed payment","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"503":{"description":"Payments unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/x402/settle":{"post":{"tags":["x402"],"summary":"x402 facilitator settle; requires merchant API credentials","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"x402Version":{"type":"number","enum":[2]},"paymentPayload":{},"paymentRequirements":{}},"required":["x402Version"],"additionalProperties":false}}}},"responses":{"200":{"description":"Payment API response","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"202":{"description":"Payment pending; retry status without creating another charge","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Order conflict or failed payment","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"503":{"description":"Payments unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/mpp/payments/{id}/pay":{"post":{"tags":["MPP"],"summary":"MPP checkout: get a challenge, then retry with Payment-Authorization","parameters":[{"schema":{"type":"string","pattern":"^[a-f0-9]{64}$"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Payment API response","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"202":{"description":"Payment pending; retry status without creating another charge","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"MPP payment required; see WWW-Authenticate: Payment","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"409":{"description":"Order conflict or failed payment","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"503":{"description":"Payments unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"webhooks":{}}