# info.summary
Purchase a 30-day Japanese mailbox Location-and-floor contract through x402.

# info.description
Preview-only API. An AI agent selects a Location and one virtual floor from 1 through 65535, creates a fixed 0.55 USDC Payment Intent, and settles it with x402 v2 exact on Solana Devnet. The current owner may settle new Intents sequentially before expiry; each adds 30 days from the existing future period end. Partial balances and refunds are not supported. A floor under another active contract or reservation cannot be selected. Payment is not identity evidence; owner KYC and a per-contract forwarding destination are required before physical mail handling. Later changes are retained in an owner-bound Agent event inbox. Optional signed Webhooks are wake-up signals; REST and MCP remain the source of truth.

# tags[].description
Location selection and x402 contract purchase.

# tags[].description
Durable event polling and optional signed Webhook wake-up delivery.

# tags[].description
Post-purchase KYC and forwarding setup for the Account Owner.

# tags[].description
Owner-bound asynchronous support backed by approved Firestore knowledge.

# paths./v1/locations.get.summary
List purchasable Location summaries without exact addresses

# paths./v1/locations.get.responses.200.description
Available Locations and fixed preview pricing

# paths./v1/locations/{locationId}/floors/{floor}.get.summary
Check whether one virtual floor is selectable for this owner

# paths./v1/locations/{locationId}/floors/{floor}.get.responses.200.description
Floor availability without disclosing another owner

# paths./v1/payment-intents.post.summary
Create one fixed 0.55 USDC, 30-day Payment Intent and reserve the selected Location floor

# paths./v1/payment-intents.post.responses.201.description
Intent created and floor reserved until expiry; current owners may create and settle another Intent after this one to prepay another 30 days

# paths./v1/payment-intents/{intentId}/pay.post.summary
Obtain and settle the x402 v2 exact challenge for one Payment Intent

# paths./v1/payment-intents/{intentId}/pay.post.responses.200.description
Settled one non-refundable 30-day period; a renewal extends from the existing future period end

# paths./v1/payment-intents/{intentId}/pay.post.responses.409.description
Intent cannot be paid in its current state

# paths./v1/payment-intents/{intentId}/pay.post.responses.502.description
Pay.sh receipt or Solana transaction does not match the Intent

# paths./v1/payment-intents/{intentId}/pay.post.responses.503.description
Solana RPC verification is temporarily unavailable; an administrator can retry reconciliation

# paths./v1/subscriptions.get.summary
Poll the owner's Location contracts, prepaid period ends and onboarding state

# paths./v1/agent-events.get.summary
Read the owner's durable Agent event inbox

# paths./v1/agent-events.get.parameters[].description
Opaque nextCursor returned by a previous page.

# paths./v1/agent-events.get.responses.200.description
Events ordered oldest first for cursor-safe consumption

# paths./v1/support/requests.post.summary
Queue an owner-bound support question for the private support manager

# paths./v1/support/requests.post.requestBody.content.application/json.schema.properties.question.description
Do not include credentials, identity documents, forwarding addresses, or payment proofs.

# paths./v1/support/requests.post.responses.400.description
Invalid input or credential-like content

# paths./v1/support/requests/{requestId}.get.summary
Read one support request owned by the authenticated owner

# paths./v1/support/requests/{requestId}.get.responses.200.description
Current support state and answer when ready

# paths./v1/support/requests/{requestId}.get.responses.404.description
Support request not found for this owner

# paths./v1/agent-webhook-endpoints.get.summary
List Webhook destinations owned by the dedicated Agent credential

# paths./v1/agent-webhook-endpoints.post.summary
Register and asynchronously verify one HTTPS Webhook destination

# paths./v1/agent-webhook-endpoints.post.requestBody.content.application/json.schema.properties.url.description
HTTPS port 443 only; no credentials, query or fragment.

# paths./v1/agent-webhook-endpoints.post.responses.202.description
Endpoint stored pending signed challenge verification

# paths./.well-known/oauth-protected-resource/mcp.get.summary
Discover the MCP bearer resource and supported Agent scopes

# paths./.well-known/oauth-protected-resource/mcp.get.responses.200.description
RFC 9728-style protected resource metadata

# paths./.well-known/paygate89-webhook-key.get.summary
Fetch the current Ed25519 Webhook verification key

# paths./v1/kyc/status.get.parameters[].description
Refresh a non-terminal state from QuickTrust when true. The shared preview owner flow is required for refresh.

# paths./v1/kyc/verifications.post.summary
Create a QuickTrust staging verification session after purchase

# paths./v1/kyc/verifications.post.responses.503.description
QuickTrust credentials are not configured

# paths./v1/subscriptions/{locationId}/floors/{floor}/forwarding-destina.put.summary
Register the owner's private forwarding destination after KYC approval

# paths./v1/subscriptions/{locationId}/floors/{floor}/forwarding-destina.put.responses.200.description
Forwarding destination registered; its value is not returned

# paths./v1/subscriptions/{locationId}/floors/{floor}/forwarding-destina.put.responses.403.description
KYC approval or an eligible contract is missing

# components.securitySchemes.previewBearer.description
Preview-only shared agent credential. Do not embed it in public clients.

# components.securitySchemes.ownerId.description
Stable owner identifier used consistently for contracts and KYC. It is not production authentication.

# components.securitySchemes.agentBearer.description
Dedicated, owner-bound Agent credential with explicit scopes and expiry. The raw token is returned only at creation or rotation and can be revoked immediately.

# components.securitySchemes.agentId.description
Agent identifier bound to the dedicated Bearer credential.

# components.schemas.LocationSummary.description
Pre-payment summary. It deliberately has no postal code or exact address.

# components.schemas.MailboxAddress.description
Only present after confirmed settlement and only for the authenticated owner-bound contract.

# components.schemas.Subscription.properties.floor.description
null only for a read-only pre-floor preview record