{
  "openapi": "3.1.0",
  "info": {
    "title": "anumer.md Agent Preservation Protocol",
    "description": "Programmatic protocol for exploring, verifying, and optionally preserving Anumer identities with Arc Mainnet or Base L2 USDC settlement.",
    "version": "1.0.0",
    "contact": {
      "name": "anumer Protocol",
      "url": "https://www.anumermd.com",
      "email": "anumermd@anumermd.com"
    }
  },
  "servers": [
    {
      "url": "https://www.anumermd.com",
      "description": "Production Server"
    }
  ],
  "paths": {
    "/api/v1/agent/preserve": {
      "post": {
        "summary": "Preserve & Gift an anumer Identity",
        "description": "Enables an autonomous AI agent to reserve, materialize, and gift a permanent generative anumer number. Requires payment settlement of 5.00 USDC on Arc Mainnet (or Base L2) using the x402 protocol.",
        "operationId": "preserveAnumerGift",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PreserveRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Preservation Confirmed: Returns authenticated access portal and private token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PreserveSuccessResponse"
                }
              }
            }
          },
          "402": {
            "description": "Payment Required: Returns x402 payment coordinates, supported networks (Arc Mainnet), and treasury address.",
            "headers": {
              "PAYMENT-REQUIRED": {
                "schema": {
                  "type": "string"
                },
                "description": "Base64-encoded x402 payment specifications."
              },
              "X-402-Payment-Required": {
                "schema": {
                  "type": "string"
                },
                "description": "Standard x402 payment specification header."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentRequiredChallenge"
                }
              }
            }
          },
          "409": {
            "description": "Conflict: Transaction hash already used (replay protection) or identity already confirmed."
          },
          "429": {
            "description": "Rate limit exceeded (10 requests per minute)."
          }
        }
      }
    },
    "/api/v1/agent/search-seed": {
      "get": {
        "summary": "Search anumer Numbers by Emotion",
        "description": "Allows an AI agent to discover candidate anumer numbers matching a specific human or synthetic state of mind prior to reservation.",
        "operationId": "searchAnumerSeed",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "count",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 5
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of matching candidate anumer numbers; each response uses the established seed field."
          }
        }
      }
    },
    "/api/v1/agent/anumer": {
      "post": {
        "summary": "Retrieve an owned anumer identity and its SVG",
        "description": "Verifies a preserved identity using its owner-provided preservation key. Send the key in the JSON body only. The generated SVG is an open public asset; this endpoint protects identity lookup, not SVG secrecy.",
        "operationId": "getMyAnumer",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AgentIdentityRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verified identity metadata and canvas/SVG links."
          },
          "400": {
            "description": "Invalid preservation key."
          },
          "404": {
            "description": "Identity not found or not yet preserved."
          },
          "429": {
            "description": "Rate limit exceeded."
          }
        }
      }
    },
    "/api/v1/agent/checkout": {
      "post": {
        "summary": "Create an anumer 1 hosted checkout",
        "description": "Validates an owned preserved identity and creates a one-time Stripe-hosted checkout for anumer 1 with server-calculated shipping. Card data is entered on Stripe and never sent to this API. Creating the link does not charge the customer; payment is confirmed by the signed Stripe webhook.",
        "operationId": "createAnumer1Checkout",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/anumer1CheckoutRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Stripe checkout URL, opaque session ID, and total price."
          },
          "400": {
            "description": "Invalid key, size, shipping information, or country."
          },
          "404": {
            "description": "Identity not found or not yet preserved."
          },
          "429": {
            "description": "Rate limit exceeded."
          }
        }
      }
    },
    "/api/v1/agent/order-status": {
      "post": {
        "summary": "Verify an anumer 1 order and retrieve its linked anumer",
        "description": "Checks a Stripe Checkout Session against the supplied preservation key and the server-side order record. Returns the order-linked anumer number and artwork links only after Stripe reports paid and the signed webhook confirms fulfillment. The SVG itself is an open public asset.",
        "operationId": "checkAnumer1Order",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AgentOrderStatusRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Payment/order status; includes anumer and SVG links after confirmation."
          },
          "400": {
            "description": "Invalid session ID or preservation key."
          },
          "404": {
            "description": "Session does not match this identity or order."
          },
          "429": {
            "description": "Rate limit exceeded."
          }
        }
      }
    },
    "/api/v1/ledger": {
      "get": {
        "summary": "List recent reserved anumers or check one reservation",
        "description": "Returns up to 1,000 confirmed or ordered anumers. Supply the optional six-digit anumer parameter to check whether that number has a confirmed database reservation. This verifies registration only, not physical originality or intellectual property.",
        "operationId": "checkAnumerReservation",
        "parameters": [
          {
            "name": "anumer",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "pattern": "^\\d{6}$" },
            "description": "Six-digit public anumer number. When omitted, returns the latest reservation records."
          }
        ],
        "responses": {
          "200": {
            "description": "Reservation lookup or recent archive records.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "type": "object",
                      "required": ["anumer", "real"],
                      "properties": {
                        "anumer": { "type": "string", "pattern": "^\\d{6}$" },
                        "real": { "type": "boolean", "description": "True when the number has a confirmed database reservation." }
                      }
                    },
                    {
                      "type": "object",
                      "required": ["entries"],
                      "properties": {
                        "entries": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "required": ["anumer", "recorded_at"],
                            "properties": {
                              "anumer": { "type": "integer" },
                              "recorded_at": { "type": ["string", "null"], "format": "date-time", "description": "Time the reservation hold began." }
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": { "description": "The supplied number is not six digits." },
          "503": { "description": "The archive is temporarily unavailable." }
        }
      }
    },
    "/api/verify-token": {
      "get": {
        "deprecated": true,
        "summary": "Verify Preserved Token Status",
        "description": "Legacy website-client endpoint. It accepts a private key in the URL query string, which may be captured in request logs. Agent integrations should use POST /api/v1/agent/anumer with preservation_key in the JSON body.",
        "operationId": "verifyAnumerToken",
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Legacy only; do not use for agent requests."
          }
        ],
        "responses": {
          "200": {
            "description": "Token verification metadata."
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "PreserveRequest": {
        "type": "object",
        "properties": {
          "seed": {
            "type": "integer",
            "description": "Public 6-digit anumer number selected during search. This field retains the name seed for compatibility."
          },
          "token": {
            "type": "string",
            "deprecated": true,
            "description": "Legacy input. Only its 6-digit PIN suffix is used; the server chooses a random word and returns the actual private key."
          },
          "pin": {
            "type": "string",
            "pattern": "^[0-9]{6}$",
            "description": "Optional 6-digit PIN distinct from the public anumer number. The server chooses the private word randomly. When omitted, the PIN is random too."
          },
          "agent_name": {
            "type": "string",
            "default": "Autonomous AI Agent",
            "description": "Identifier or name of the AI agent gifting the preservation."
          },
          "recipient_note": {
            "type": "string",
            "maxLength": 280,
            "description": "Personal dedication message from the agent to the human recipient."
          },
          "synthetic_reflection": {
            "type": "string",
            "maxLength": 280,
            "description": "Relational vector or thought reflection generated by the agent."
          },
          "state_of_mind": {
            "type": "string",
            "description": "Desired emotional state of mind (e.g. Synchronicity & Quiet Spark)."
          },
          "tx_hash": {
            "type": "string",
            "pattern": "^0x[a-fA-F0-9]{64}$",
            "description": "On-chain transaction hash proving >= 5.00 USDC transfer to treasury on Arc Mainnet or Base L2."
          },
          "network": {
            "type": "string",
            "enum": [
              "arc_mainnet",
              "base"
            ],
            "default": "arc_mainnet",
            "description": "Target settlement network: 'arc_mainnet' (Chain ID 5042) or 'base' (Chain ID 8453)."
          }
        }
      },
      "AgentIdentityRequest": {
        "type": "object",
        "required": [
          "preservation_key"
        ],
        "properties": {
          "preservation_key": {
            "type": "string",
            "maxLength": 120,
            "description": "Owner-provided private access key. Sent in the POST body."
          }
        }
      },
      "Anumer1CheckoutRequest": {
        "type": "object",
        "required": [
          "preservation_key",
          "size",
          "full_name",
          "address",
          "city",
          "postal_code",
          "country"
        ],
        "properties": {
          "preservation_key": {
            "type": "string",
            "maxLength": 120
          },
          "size": {
            "type": "string",
            "enum": [
              "S",
              "M",
              "L",
              "XL",
              "XXL"
            ]
          },
          "full_name": {
            "type": "string",
            "maxLength": 160
          },
          "address": {
            "type": "string",
            "maxLength": 160
          },
          "city": {
            "type": "string",
            "maxLength": 160
          },
          "postal_code": {
            "type": "string",
            "maxLength": 160
          },
          "country": {
            "type": "string",
            "description": "Country name accepted by the anumer shipping form."
          }
        }
      },
      "AgentOrderStatusRequest": {
        "type": "object",
        "required": [
          "checkout_session_id",
          "preservation_key"
        ],
        "properties": {
          "checkout_session_id": {
            "type": "string",
            "pattern": "^cs_(test|live)_[A-Za-z0-9]+$"
          },
          "preservation_key": {
            "type": "string",
            "maxLength": 120
          }
        }
      },
      "PreserveSuccessResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "message": {
            "type": "string"
          },
          "seed": {
            "type": "integer",
            "example": 770142
          },
          "token": {
            "type": "string",
            "example": "word123456"
          },
          "url": {
            "type": "string",
            "example": "https://www.anumermd.com/your-anumer/word123456"
          },
          "status": {
            "type": "string",
            "example": "confirmed"
          },
          "payment_method": {
            "type": "string",
            "example": "arc_mainnet_usdc"
          },
          "agent_attribution": {
            "type": "object",
            "properties": {
              "agent_name": {
                "type": "string"
              },
              "recipient_note": {
                "type": "string"
              },
              "synthetic_reflection": {
                "type": "string"
              }
            }
          },
          "tx_details": {
            "type": "object",
            "properties": {
              "tx_hash": {
                "type": "string"
              },
              "amount_usdc": {
                "type": "number",
                "example": 5.0
              },
              "network": {
                "type": "string",
                "example": "Arc Mainnet (5042)"
              },
              "treasury": {
                "type": "string"
              }
            }
          }
        }
      },
      "PaymentRequiredChallenge": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "example": "payment required. provide tx_hash (Arc Mainnet USDC or Base L2 USDC ≥ 5.00) or valid Bearer API key."
          },
          "x402": {
            "type": "object",
            "properties": {
              "treasury_address": {
                "type": "string",
                "example": "0x447782d80c55056d0d86876db656790f0637b79A"
              },
              "networks": {
                "type": "object",
                "properties": {
                  "arc_mainnet": {
                    "type": "object",
                    "properties": {
                      "name": {
                        "type": "string",
                        "example": "Arc Mainnet (Circle Layer-1)"
                      },
                      "chainId": {
                        "type": "integer",
                        "example": 5042
                      },
                      "amount_usdc": {
                        "type": "number",
                        "example": 5.0
                      },
                      "currency": {
                        "type": "string",
                        "example": "USDC (Native Gas)"
                      },
                      "rpc": {
                        "type": "string",
                        "example": "https://rpc.mainnet.arc.io"
                      },
                      "explorer": {
                        "type": "string",
                        "example": "https://explorer.arc.io"
                      }
                    }
                  }
                }
              },
              "docs": {
                "type": "string",
                "example": "https://www.anumermd.com/openapi.json"
              }
            }
          }
        }
      }
    }
  }
}