# 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 55 USDC Payment Intent, and settles it with x402 v2 exact on Solana Devnet. 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.

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

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

# 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 a 15-minute Payment Intent and reserve the selected Location floor

# paths./v1/payment-intents.post.responses.201.description
Intent created and floor reserved until expiry; use payPath with an x402-capable client

# 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 30-day contract with snapshotted Japanese and English mailbox address

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

# paths./v1/subscriptions.get.summary
List the owner's Location contracts and onboarding state

# paths./v1/kyc/status.get.parameters[].description
Refresh a non-terminal state from QuickTrust when true.

# 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.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