{
  "openapi": "3.1.0",
  "info": {
    "title": "GotSOL.app",
    "version": "0.1.0",
    "summary": "USDC payments on Solana for agents.",
    "description": "Privy holds the wallet keys. An agent receives an API key, not the private key. Outgoing USDC transfers are 0.25% through December 31, 2027. Incoming transfers, payment links, and x402 payments are 0%. On POST /api/agent/transfer, the Solana network fee is paid in USDC and the sender does not need SOL. The wallet that signs an x402 payment pays the Solana network fee in SOL. Does not support sanctioned regions.",
    "contact": {
      "name": "GotSOL.app",
      "email": "Ryan@GotSOLpay.com",
      "url": "https://gotsol.app/contact"
    },
    "x-logo": {
      "url": "https://gotsol.app/logo-256.png"
    }
  },
  "servers": [{ "url": "https://gotsol.app" }],
  "security": [{ "bearerAuth": [] }],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Send the agent API key as Authorization: Bearer. The key starts with gotsol_ and is returned once by POST /api/agent/wallets."
      }
    }
  },
  "paths": {
    "/api/agent/wallets": {
      "post": {
        "operationId": "createWallet",
        "summary": "Open a Solana wallet",
        "security": [],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": { "type": "string" },
                  "idempotencyKey": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wallet created. The API key is shown once.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["wallet", "walletId", "apiKey"],
                  "properties": {
                    "wallet": { "type": "string", "description": "Solana address" },
                    "walletId": { "type": "string" },
                    "apiKey": { "type": "string", "description": "Starts with gotsol_. Shown once." },
                    "message": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/agent/transfer": {
      "post": {
        "operationId": "sendUsdc",
        "summary": "Send USDC",
        "security": [{ "bearerAuth": [] }],
        "x-guidance": "Use this when the agent should send USDC. Pass Authorization: Bearer and the gotsol_ API key. The sender does not need SOL.",
        "description": "Sends USDC from the wallet for this API key. The recipient receives the amount minus 0.25% through December 31, 2027. The Solana network fee is paid in USDC. The sender does not need SOL. A missing recipient USDC account is opened in the same transaction.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["to", "amount"],
                "properties": {
                  "to": { "type": "string", "description": "Recipient Solana address" },
                  "amount": { "type": "number", "description": "USDC debited from the sender" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The send was submitted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["signature", "recipientReceivesUsdc", "feeUsdc"],
                  "properties": {
                    "signature": { "type": "string" },
                    "pending": { "type": "boolean" },
                    "recipientReceivesUsdc": { "type": "string" },
                    "feeUsdc": { "type": "string", "description": "The 0.25% GotSOL.app fee" },
                    "networkFeeUsdc": { "type": "string", "description": "USDC kept for the Solana network fee after confirmation" },
                    "message": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/agent/payment-links": {
      "get": {
        "operationId": "listPaymentLinks",
        "summary": "List payment links",
        "security": [{ "bearerAuth": [] }],
        "x-guidance": "Use this to list payment links for the API key. Pass Authorization: Bearer and the gotsol_ API key.",
        "responses": { "200": { "description": "Payment links for this API key." } }
      },
      "post": {
        "operationId": "createPaymentLink",
        "summary": "Create a USDC payment link",
        "security": [{ "bearerAuth": [] }],
        "x-guidance": "Use this to request an incoming USDC payment. Pass Authorization: Bearer and the gotsol_ API key. Incoming payments are 0%.",
        "description": "Incoming payments are 0%. The payer of an x402 settlement pays the Solana network fee in SOL.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["amount"],
                "properties": {
                  "amount": { "type": "number" },
                  "memo": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Payment link created.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": { "type": "string" },
                    "payUrl": { "type": "string" },
                    "solanaPayUrl": { "type": "string" },
                    "x402Url": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/x402/pay/{linkId}": {
      "get": {
        "operationId": "x402Pay",
        "summary": "Request or settle an x402 USDC payment",
        "security": [],
        "description": "Without PAYMENT-SIGNATURE the response is HTTP 402. The paying wallet signs the USDC transfer and pays the Solana network fee in SOL. Retry with PAYMENT-SIGNATURE set to the base64 payment payload.",
        "parameters": [{ "name": "linkId", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": {
          "402": { "description": "Payment required." },
          "200": { "description": "Payment settled." },
          "404": { "description": "Payment link not found." }
        }
      }
    },
    "/api/mcp": {
      "post": {
        "operationId": "mcp",
        "summary": "MCP endpoint",
        "security": [{ "bearerAuth": [] }],
        "x-guidance": "Point an MCP client at https://gotsol.app/api/mcp. Pass the gotsol_ API key as Authorization: Bearer, or as the tool argument bearerToken.",
        "description": "Live MCP server version 0.1.0 at https://gotsol.app/api/mcp. Tools include create_wallet, create_payment_link, and send_usdc. Pass the API key as Authorization: Bearer or as the tool argument bearerToken.",
        "responses": { "200": { "description": "MCP response." } }
      }
    }
  }
}