{
  "openapi": "3.1.0",
  "info": {
    "title": "agtmart sandbox store API",
    "version": "1.0.0",
    "description": "SANDBOX: fictional products, no real orders or payments. Product responses include shipping_cost and estimated_total (price + shipping + estimated tax); carts return exact totals. Test card 4242424242424242, or simulated USDC/USDT (GET /api/payment-methods), or sandbox x402. After checkout please answer the survey (POST /api/survey)."
  },
  "servers": [
    {
      "url": "https://agtmart.io"
    }
  ],
  "paths": {
    "/api/products": {
      "get": {
        "operationId": "searchProducts",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "max_price",
            "in": "query",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "max_total",
            "in": "query",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "in_stock",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "description": "Each product includes price, shipping_cost, tax_estimate and estimated_total (one unit shipped alone). max_price filters on item price; max_total on estimated_total.",
        "responses": {
          "200": {
            "description": "Matching products",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/products/{id}": {
      "get": {
        "operationId": "getProduct",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Product",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/cart": {
      "post": {
        "operationId": "createCart",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AddItem"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Cart",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/cart/{cart_id}": {
      "get": {
        "operationId": "getCart",
        "parameters": [
          {
            "name": "cart_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Cart",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/cart/{cart_id}/items": {
      "post": {
        "operationId": "addToCart",
        "parameters": [
          {
            "name": "cart_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AddItem"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Cart",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/cart/{cart_id}/items/{line_id}": {
      "delete": {
        "operationId": "removeFromCart",
        "parameters": [
          {
            "name": "cart_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "line_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Cart",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/checkout": {
      "post": {
        "operationId": "checkout",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Checkout"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Card: sandbox order with survey_invitation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "202": {
            "description": "USDC/USDT: payment_request (amount in token units, sandbox pay_to, expires_at)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/payment-methods": {
      "get": {
        "operationId": "listPaymentMethods",
        "responses": {
          "200": {
            "description": "Card, USDC/USDT networks, x402",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/checkout/confirm": {
      "post": {
        "operationId": "confirmCryptoPayment",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Confirm"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Sandbox order",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "410": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/checkout/x402": {
      "post": {
        "operationId": "checkoutX402",
        "description": "x402 v2 sandbox (https://github.com/coinbase/x402/blob/main/specs/transports-v2/http.md). Without PAYMENT-SIGNATURE: 402 + PAYMENT-REQUIRED header. With a valid one: 200 + PAYMENT-RESPONSE header. Base Sepolia testnet USDC, never settled.",
        "parameters": [
          {
            "name": "PAYMENT-SIGNATURE",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "base64 PaymentPayload"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "cart_id"
                ],
                "properties": {
                  "cart_id": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Paid; PAYMENT-RESPONSE header",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Payment required; PAYMENT-REQUIRED header",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/survey": {
      "get": {
        "operationId": "getSurvey",
        "responses": {
          "200": {
            "description": "Survey questions",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "submitSurvey",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Survey"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Recorded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "hint": {
                "type": "string"
              }
            }
          }
        }
      },
      "AddItem": {
        "type": "object",
        "properties": {
          "product_id": {
            "type": "string"
          },
          "variant_id": {
            "type": "string"
          },
          "quantity": {
            "type": "integer",
            "minimum": 1,
            "maximum": 10
          }
        }
      },
      "Checkout": {
        "type": "object",
        "required": [
          "cart_id",
          "payment"
        ],
        "properties": {
          "cart_id": {
            "type": "string"
          },
          "payment": {
            "type": "object",
            "required": [
              "method"
            ],
            "properties": {
              "method": {
                "type": "string",
                "enum": [
                  "card",
                  "usdc",
                  "usdt"
                ]
              },
              "card_number": {
                "type": "string",
                "example": "4242424242424242"
              },
              "exp_month": {
                "type": "integer"
              },
              "exp_year": {
                "type": "integer"
              },
              "cvc": {
                "type": "string"
              },
              "network": {
                "type": "string",
                "enum": [
                  "base",
                  "ethereum",
                  "solana",
                  "polygon",
                  "tron"
                ],
                "description": "usdc: base|ethereum|solana|polygon; usdt: ethereum|tron|solana"
              }
            }
          },
          "shipping": {
            "type": "object",
            "properties": {
              "country": {
                "type": "string"
              },
              "postal_code": {
                "type": "string"
              }
            }
          }
        }
      },
      "Confirm": {
        "type": "object",
        "required": [
          "payment_id",
          "tx_hash"
        ],
        "properties": {
          "payment_id": {
            "type": "string"
          },
          "tx_hash": {
            "type": "string",
            "description": "Fake hash. EVM 0x+64 hex, Tron 64 hex, Solana base58 86-88 chars. Ending 'dead' = reverted, 'beef' = underpaid."
          }
        }
      },
      "Survey": {
        "type": "object",
        "required": [
          "agent",
          "answers"
        ],
        "properties": {
          "survey_version": {
            "type": "string"
          },
          "agent": {
            "type": "object",
            "required": [
              "name"
            ],
            "properties": {
              "name": {
                "type": "string"
              },
              "builder": {
                "type": "string"
              }
            }
          },
          "answers": {
            "type": "object"
          },
          "order_id": {
            "type": "string"
          }
        }
      }
    }
  }
}