{ "openapi": "3.1.0", "info": { "title": "Private Payments API", "version": "0.1.0", "description": "REST API for building private SPL token transactions on Solana and MagicBlock ephemeral rollups.\n\nDocumentation: https://docs.magicblock.gg/pages/private-ephemeral-rollups-pers/how-to-guide/quickstart" }, "servers": [ { "url": "https://payments.magicblock.app", "description": "Mainnet - Private Payments API" } ], "components": { "schemas": { "HealthResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] } }, "required": [ "status" ] }, "UnsignedTransactionResponse": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "deposit", "withdraw", "transfer" ] }, "version": { "type": "string", "enum": [ "legacy", "v0" ] }, "transactionBase64": { "type": "string" }, "sendTo": { "$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" } }, "required": [ "kind", "version", "transactionBase64", "sendTo", "recentBlockhash", "lastValidBlockHeight", "instructionCount", "requiredSigners" ] }, "BalanceLocation": { "type": "string", "enum": [ "base", "ephemeral" ] }, "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" ] }, { "type": "string" } ], "example": "mainnet", "description": "Optional. Use `mainnet` for BASE_RPC_URL and EPHEMERAL_RPC_URL, `devnet` for BASE_DEVNET_RPC_URL and EPHEMERAL_DEVNET_RPC_URL, or provide a custom http(s) RPC URL to override 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 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." }, "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" } }, "required": [ "owner", "amount" ], "example": { "owner": "3rXKwQ1kpjBd5tdcco32qsvqUh1BnZjcYnS5kYrP7AYE", "amount": 1, "initIfMissing": true, "initVaultIfMissing": true, "initAtasIfMissing": true, "idempotent": true } }, "WithdrawRequest": { "type": "object", "properties": { "owner": { "type": "string", "example": "3rXKwQ1kpjBd5tdcco32qsvqUh1BnZjcYnS5kYrP7AYE" }, "cluster": { "anyOf": [ { "type": "string", "enum": [ "mainnet", "devnet" ] }, { "type": "string" } ], "example": "mainnet", "description": "Optional. Use `mainnet` for BASE_RPC_URL and EPHEMERAL_RPC_URL, `devnet` for BASE_DEVNET_RPC_URL and EPHEMERAL_DEVNET_RPC_URL, or provide a custom http(s) RPC URL to override 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." }, "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" ] }, { "type": "string" } ], "example": "mainnet", "description": "Optional. Use `mainnet` for BASE_RPC_URL and EPHEMERAL_RPC_URL, `devnet` for BASE_DEVNET_RPC_URL and EPHEMERAL_DEVNET_RPC_URL, or provide a custom http(s) RPC URL to override 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": "3rXKwQ1kpjBd5tdcco32qsvqUh1BnZjcYnS5kYrP7AYE" }, "to": { "type": "string", "example": "Bt9oNR5cCtnfuMmXgWELd6q5i974PdEMQDUE55nBC57L" }, "cluster": { "anyOf": [ { "type": "string", "enum": [ "mainnet", "devnet" ] }, { "type": "string" } ], "example": "mainnet", "description": "Optional. Use `mainnet` for BASE_RPC_URL and EPHEMERAL_RPC_URL, `devnet` for BASE_DEVNET_RPC_URL and EPHEMERAL_DEVNET_RPC_URL, or provide a custom http(s) RPC URL to override the base RPC while keeping the configured ephemeral RPC." }, "mint": { "type": "string", "example": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" }, "amount": { "type": "integer", "minimum": 1, "example": 1000000, "description": "Base-unit amount as an integer JSON value with minimum 1." }, "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", "pattern": "^\\d+$", "example": "0", "description": "Optional. Private transfer only. Defaults to 0." }, "maxDelayMs": { "type": "string", "pattern": "^\\d+$", "example": "0", "description": "Optional. Private transfer only. Defaults to 0 when omitted, or to minDelayMs when minDelayMs is set." }, "clientRefId": { "type": "string", "pattern": "^\\d+$", "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." }, "gasless": { "type": "boolean", "example": true, "description": "Optional. When true, the API uses the configured sponsor as transaction fee payer and prepends a relay-fee token transfer to the sponsor ATA." }, "legacy": { "type": "boolean", "description": "Optional. Defaults to false. When true, skips lookup-table compilation and returns a legacy transaction." } }, "required": [ "from", "to", "mint", "amount", "visibility", "fromBalance", "toBalance" ], "example": { "from": "3rXKwQ1kpjBd5tdcco32qsvqUh1BnZjcYnS5kYrP7AYE", "to": "Bt9oNR5cCtnfuMmXgWELd6q5i974PdEMQDUE55nBC57L", "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "amount": 1000000, "visibility": "private", "fromBalance": "base", "toBalance": "base", "initIfMissing": true, "initAtasIfMissing": true, "initVaultIfMissing": false, "memo": "Order #1042", "minDelayMs": "0", "maxDelayMs": "0", "clientRefId": "42", "split": 1, "gasless": true } }, "TransferVisibility": { "type": "string", "enum": [ "public", "private" ] }, "BalanceResponse": { "type": "object", "properties": { "address": { "type": "string", "example": "Bt9oNR5cCtnfuMmXgWELd6q5i974PdEMQDUE55nBC57L" }, "mint": { "type": "string", "example": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" }, "ata": { "type": "string", "example": "3rXKwQ1kpjBd5tdcco32qsvqUh1BnZjcYnS5kYrP7AYE" }, "location": { "$ref": "#/components/schemas/BalanceLocation" }, "balance": { "type": "string" } }, "required": [ "address", "mint", "ata", "location", "balance" ] }, "MintInitializationResponse": { "type": "object", "properties": { "mint": { "type": "string" }, "validator": { "type": "string" }, "transferQueue": { "type": "string" }, "initialized": { "type": "boolean" } }, "required": [ "mint", "validator", "transferQueue", "initialized" ] }, "ChallengeResponse": { "type": "object", "properties": { "challenge": { "type": "string", "example": "1234567890" } }, "required": [ "challenge" ] }, "LoginRequest": { "type": "object", "properties": { "pubkey": { "type": "string", "example": "Bt9oNR5cCtnfuMmXgWELd6q5i974PdEMQDUE55nBC57L" }, "challenge": { "type": "string", "example": "1234567890" }, "signature": { "type": "string", "example": "1234567890" }, "cluster": { "anyOf": [ { "type": "string", "enum": [ "mainnet", "devnet" ] }, { "type": "string" } ], "example": "mainnet" }, "mock": { "type": "boolean", "example": false } }, "required": [ "pubkey", "challenge", "signature" ] }, "LoginResponse": { "type": "object", "properties": { "token": { "type": "string", "example": "1234567890" } }, "required": [ "token" ] }, "SwapMode": { "type": "string", "enum": [ "ExactIn", "ExactOut" ] }, "InstructionVersion": { "type": "string", "enum": [ "V1", "V2" ] }, "QuoteResponse": { "type": "object", "additionalProperties": true, "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", "additionalProperties": true, "properties": { "swapInfo": { "type": "object", "additionalProperties": true }, "percent": { "type": "integer", "minimum": 0 }, "bps": { "type": [ "integer", "null" ], "minimum": 0 } } } }, "instructionVersion": { "anyOf": [ { "$ref": "#/components/schemas/InstructionVersion" }, { "type": "null" } ] }, "platformFee": { "anyOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ] }, "contextSlot": { "type": "integer", "minimum": 0 }, "timeTaken": { "type": "number" } }, "required": [ "inputMint", "inAmount", "outputMint", "outAmount", "otherAmountThreshold", "swapMode", "slippageBps", "priceImpactPct", "routePlan" ] }, "SwapRequest": { "type": "object", "additionalProperties": true, "properties": { "userPublicKey": { "type": "string", "example": "3rXKwQ1kpjBd5tdcco32qsvqUh1BnZjcYnS5kYrP7AYE" }, "quoteResponse": { "$ref": "#/components/schemas/QuoteResponse" }, "payer": { "type": "string" }, "wrapAndUnwrapSol": { "type": "boolean" }, "useSharedAccounts": { "type": "boolean" }, "feeAccount": { "type": "string" }, "trackingAccount": { "type": "string" }, "prioritizationFeeLamports": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "object", "additionalProperties": true } ] }, "asLegacyTransaction": { "type": "boolean" }, "destinationTokenAccount": { "type": "string" }, "nativeDestinationAccount": { "type": "string" }, "dynamicComputeUnitLimit": { "type": "boolean" }, "skipUserAccountsRpcCalls": { "type": "boolean" }, "dynamicSlippage": { "type": "boolean" }, "computeUnitPriceMicroLamports": { "type": "integer", "minimum": 0 }, "blockhashSlotsToExpiry": { "type": "integer", "minimum": 0 }, "positiveSlippage": { "type": "object", "additionalProperties": true }, "visibility": { "type": "string", "enum": [ "public", "private" ], "description": "`public` (default) proxies Jupiter/Metis as-is. `private` routes the output through a scheduled private transfer." }, "destination": { "type": "string", "description": "Required when `visibility=\"private\"`." }, "minDelayMs": { "type": "string", "pattern": "^\\d+$", "description": "Required when `visibility=\"private\"`." }, "maxDelayMs": { "type": "string", "pattern": "^\\d+$", "description": "Required when `visibility=\"private\"`. Max 600000." }, "split": { "type": "integer", "minimum": 1, "maximum": 14, "description": "Required when `visibility=\"private\"`." }, "clientRefId": { "type": "string", "pattern": "^\\d+$" }, "validator": { "type": "string" } }, "required": [ "userPublicKey", "quoteResponse" ] }, "SwapResponse": { "type": "object", "additionalProperties": true, "properties": { "swapTransaction": { "type": "string" }, "lastValidBlockHeight": { "type": "integer", "minimum": 0 }, "prioritizationFeeLamports": { "type": "integer", "minimum": 0 }, "privateTransfer": { "type": "object", "description": "Present only when `visibility=\"private\"`.", "properties": { "stashAta": { "type": "string" }, "hydraCrankPda": { "type": "string" }, "shuttleId": { "type": "integer", "minimum": 0 } }, "required": [ "stashAta", "hydraCrankPda", "shuttleId" ] } }, "required": [ "swapTransaction" ] }, "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": {}, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Authentication token issued by `POST /v1/spl/login`." } } }, "paths": { "/health": { "get": { "tags": [ "Meta" ], "responses": { "200": { "description": "Health check", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } } } } }, "/v1/spl/challenge": { "get": { "tags": [ "Auth" ], "description": "Generate a challenge string for the wallet to sign.", "parameters": [ { "name": "pubkey", "in": "query", "required": true, "schema": { "type": "string", "example": "Bt9oNR5cCtnfuMmXgWELd6q5i974PdEMQDUE55nBC57L" }, "description": "The public key of the wallet that will read private data." }, { "name": "cluster", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "enum": [ "mainnet", "devnet" ] }, { "type": "string" } ], "example": "mainnet" } }, { "name": "mock", "in": "query", "required": false, "schema": { "type": "boolean", "example": false } } ], "responses": { "200": { "description": "Challenge string", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChallengeResponse" } } } }, "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": [ "Auth" ], "description": "Login the wallet to the Private Ephemeral Rollup.", "requestBody": { "required": true, "description": "Login request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginRequest" } } } }, "responses": { "200": { "description": "Authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginResponse" } } } }, "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/spl/deposit": { "post": { "tags": [ "SPL" ], "description": "Deposit SPL tokens from Solana into an ephemeral rollup.", "requestBody": { "required": true, "description": "Deposit request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DepositRequest" } } } }, "responses": { "200": { "description": "Unsigned 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" } } } } } } }, "/v1/spl/withdraw": { "post": { "tags": [ "SPL" ], "description": "Withdraw SPL tokens from an ephemeral rollup back to Solana.", "requestBody": { "required": true, "description": "Withdraw request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithdrawRequest" } } } }, "responses": { "200": { "description": "Unsigned 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" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } } } }, "/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": 4, "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 or privately through an ephemeral rollup. Pass an optional `Authorization: Bearer ` header for transfers that need to connect to the Private Ephemeral Rollup.", "parameters": [ { "name": "authorization", "in": "header", "required": false, "schema": { "type": "string", "example": "Bearer 1234567890" }, "description": "Optional. Authentication token for requests that need to connect to the Private Ephemeral Rollup." } ], "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 or unsupported transfer route (`UNSUPPORTED_TRANSFER_ROUTE`)", "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.", "parameters": [ { "name": "address", "in": "query", "required": true, "schema": { "type": "string", "example": "Bt9oNR5cCtnfuMmXgWELd6q5i974PdEMQDUE55nBC57L" } }, { "name": "mint", "in": "query", "required": true, "schema": { "type": "string", "example": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" } }, { "name": "cluster", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "enum": [ "mainnet", "devnet" ] }, { "type": "string" } ], "example": "mainnet" }, "description": "Optional. Use `mainnet` for BASE_RPC_URL and EPHEMERAL_RPC_URL, `devnet` for BASE_DEVNET_RPC_URL and EPHEMERAL_DEVNET_RPC_URL, or provide a custom http(s) RPC URL to override the base RPC while keeping the configured ephemeral RPC." } ], "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" } } } }, "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 balance for the owner's ATA on the ephemeral RPC. Requires authentication via the Private Ephemeral Rollup login flow.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "authorization", "in": "header", "required": true, "schema": { "type": "string", "example": "Bearer 1234567890" }, "description": "Required. Authentication token issued by `POST /v1/spl/login`." }, { "name": "address", "in": "query", "required": true, "schema": { "type": "string", "example": "Bt9oNR5cCtnfuMmXgWELd6q5i974PdEMQDUE55nBC57L" } }, { "name": "mint", "in": "query", "required": true, "schema": { "type": "string", "example": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" } }, { "name": "cluster", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "enum": [ "mainnet", "devnet" ] }, { "type": "string" } ], "example": "mainnet" }, "description": "Optional. Use `mainnet` for BASE_RPC_URL and EPHEMERAL_RPC_URL, `devnet` for BASE_DEVNET_RPC_URL and EPHEMERAL_DEVNET_RPC_URL, or provide a custom http(s) RPC URL to override the base RPC while keeping the configured ephemeral RPC." } ], "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" } } } }, "400": { "description": "Missing auth token (`MISSING_AUTH_TOKEN`) or other query error", "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": [ { "name": "mint", "in": "query", "required": true, "schema": { "type": "string", "example": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" } }, { "name": "cluster", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "enum": [ "mainnet", "devnet" ] }, { "type": "string" } ], "example": "mainnet" } }, { "name": "validator", "in": "query", "required": false, "schema": { "type": "string", "example": "MAS1Dt9qreoRMQ14YQuhg8UTZMMzDdKhmkZMECCzk57" }, "description": "Optional. Defaults to the selected ephemeral RPC identity resolved via `getIdentity`." } ], "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/swap/quote": { "get": { "tags": [ "Swap" ], "description": "Get a swap quote between two SPL mints. Proxies the configured Triton Metis Swap API.", "parameters": [ { "name": "inputMint", "in": "query", "required": true, "schema": { "type": "string", "example": "So11111111111111111111111111111111111111112" } }, { "name": "outputMint", "in": "query", "required": true, "schema": { "type": "string", "example": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" } }, { "name": "amount", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d+$", "example": "1000000" } }, { "name": "slippageBps", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "example": 50 } }, { "name": "swapMode", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/SwapMode" } }, { "name": "dexes", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "excludeDexes", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "restrictIntermediateTokens", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "onlyDirectRoutes", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "asLegacyTransaction", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "platformFeeBps", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "maxAccounts", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "instructionVersion", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/InstructionVersion" } }, { "name": "dynamicSlippage", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "forJitoBundle", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "supportDynamicIntermediateTokens", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Swap quote", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteResponse" } } } }, "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. Supports `visibility=\"public\"` (default upstream pass-through) and `visibility=\"private\"` (forces output into a program-owned stash ATA and appends a `schedule_private_transfer` instruction).", "requestBody": { "required": true, "description": "Swap request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SwapRequest" } } } }, "responses": { "200": { "description": "Swap transaction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SwapResponse" } } } }, "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" } } } } } } }, "/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`", "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" } } } }, "500": { "description": "MCP JSON-RPC error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpResponse" } } } } }, "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" } } } } } } } } }, "webhooks": {} }