{ "openapi": "3.1.0", "info": { "title": "Go Bag", "version": "1.0.0", "description": "Prepaid eSIM data plans for AI agents, paid per purchase in USDC on Base with x402. 1441 plans, $0.99–$202.99.", "x-guidance": "Go Bag sells prepaid eSIM data plans to AI agents, paid in USDC on Base (eip155:8453) with x402 v2 (scheme exact).\n1. Choose a plan: GET /catalog (filter with ?country= and ?data=). Note the plan's launch_sku_id and price_usd.\n2. Make a delivery key: generate an Ed25519 key pair for this purchase and keep the private key until you have retrieved the eSIM. Send only the SPKI public key PEM. Use a new key for every purchase.\n3. Buy: POST /buy with JSON {\"launch_sku_id\": \"...\", \"ordered_quantity\": 1, \"delivery_entitlement\": {\"mode\": \"delivery_public_key\", \"delivery_public_key_pem\": \"...\"}}. The unpaid reply is HTTP 402 whose single requirement is the exact price of that order. Pay by sending the same POST /buy body again with the x402 payment header. With AgentCash: agentcash fetch https://gobagesim.com/buy -m POST -b '' --max-amount (AgentCash refuses payments above $5 unless --max-amount is raised).\n4. The paid reply is HTTP 200 with fulfillment \"processing\", the order_id and next_step. Poll GET /orders/{order_id}/fulfill without a payment header every 2 seconds until fulfillment is \"issued\" (usually under 15 seconds). HTTP 409 means settlement is still being confirmed: keep polling for up to 3 minutes.\n5. Retrieve: POST /orders/{order_id}/delivery/retrieve with {\"mode\": \"delivery_public_key\", \"nonce\": \"\", \"expiresAtMs\": , \"signatureB64\": \"\"}. Sign the UTF-8 text agent-commerce-lab.x402-esim.delivery.v1|retrieve_install|{order_id}|{key_fingerprint}|{nonce}|{expiresAtMs}, where key_fingerprint is the lowercase hex SHA-256 of your public key's SPKI DER bytes. The reply contains the eSIM install material.\nSafety: one delivery key buys one order. As long as every attempt goes through POST /buy, sending the same body again never charges twice; it returns that order's current status. If a paid reply is lost, times out or is a 5xx, do not pay again: re-send the same POST /buy body without payment, or poll GET /orders/{order_id}/fulfill, to see whether the payment went through. Do not mix doors for one delivery key.\nAlternative without Ed25519: delivery_entitlement {\"mode\": \"claim_capability\", \"claim_hash\": \"\"}, then retrieve with {\"mode\": \"claim_capability\", \"claimSecret\": \"\"}.\nThe two-step flow also works: POST /orders, then pay GET /orders/{order_id}/fulfill directly." }, "servers": [ { "url": "https://gobagesim.com" } ], "paths": { "/buy": { "post": { "operationId": "purchaseEsim", "summary": "Buy an eSIM plan (x402 paid)", "description": "Send the order body. Unpaid: HTTP 402 with the exact requirement for this order. Paid: the same body with the x402 payment header. Re-sending the same body returns the order's status and never charges twice.", "x-payment-info": { "protocols": [ { "x402": {} } ], "price": { "mode": "dynamic", "currency": "USD", "min": "0.99", "max": "202.99" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "launch_sku_id", "delivery_entitlement" ], "properties": { "launch_sku_id": { "type": "string", "pattern": "^[a-z0-9_:-]{1,80}$", "description": "launch_sku_id of a plan from GET /catalog" }, "ordered_quantity": { "type": "integer", "const": 1, "description": "Always 1" }, "delivery_entitlement": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "mode", "delivery_public_key_pem" ], "properties": { "mode": { "const": "delivery_public_key" }, "delivery_public_key_pem": { "type": "string", "description": "Ed25519 SPKI public key PEM. Keep the private key; it signs the eSIM retrieval." } } }, { "type": "object", "additionalProperties": false, "required": [ "mode", "claim_hash" ], "properties": { "mode": { "const": "claim_capability" }, "claim_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Lowercase hex SHA-256 of a high-entropy secret you keep and present at retrieval." } } } ] } }, "example": { "launch_sku_id": "plan_01110f9b07b9b07a9156393f0dfa251511bdd25fb7821120c1b76b078e3c9693", "ordered_quantity": 1, "delivery_entitlement": { "mode": "delivery_public_key", "delivery_public_key_pem": "-----BEGIN PUBLIC KEY-----\n\n-----END PUBLIC KEY-----" } } } } } }, "responses": { "200": { "description": "Paid (or already paid): fulfillment status for the order", "content": { "application/json": { "schema": { "type": "object", "required": [ "order_id", "status", "payment", "fulfillment" ], "properties": { "order_id": { "type": "string" }, "status": { "type": "string" }, "payment": { "type": "string" }, "fulfillment": { "type": "string", "description": "processing until the eSIM is issued, then issued" }, "transaction": { "type": "string" }, "next_step": { "type": "object" } } } } } }, "400": { "description": "Invalid order body", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "order_id": { "type": "string" } } } } } }, "402": { "description": "Payment Required" }, "409": { "description": "This delivery key is already bound to another order, its order expired unpaid, or settlement is still being confirmed", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "order_id": { "type": "string" } } } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "order_id": { "type": "string" } } } } } } } } }, "/catalog": { "get": { "operationId": "listPlans", "summary": "List eSIM plans (free)", "security": [], "parameters": [ { "name": "country", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Country name or ISO code" }, { "name": "data", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Data amount, for example 1GB or unlimited" } ], "responses": { "200": { "description": "Catalog with products and buyer_interface", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/orders": { "post": { "operationId": "createOrder", "summary": "Create an unpaid order for the two-step flow (free)", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "launch_sku_id", "delivery_entitlement" ], "properties": { "launch_sku_id": { "type": "string" }, "ordered_quantity": { "type": "integer", "const": 1 }, "delivery_entitlement": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "mode", "delivery_public_key_pem" ], "properties": { "mode": { "const": "delivery_public_key" }, "delivery_public_key_pem": { "type": "string", "description": "Ed25519 SPKI public key PEM. Keep the private key; it signs the eSIM retrieval." } } }, { "type": "object", "additionalProperties": false, "required": [ "mode", "claim_hash" ], "properties": { "mode": { "const": "claim_capability" }, "claim_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Lowercase hex SHA-256 of a high-entropy secret you keep and present at retrieval." } } } ] } } } } } }, "responses": { "201": { "description": "Order created; pay at GET /orders/{order_id}/fulfill", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/orders/{order_id}/delivery/retrieve": { "post": { "operationId": "retrieveEsim", "summary": "Retrieve the issued eSIM with your delivery key (free)", "security": [], "parameters": [ { "name": "order_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "mode", "nonce", "expiresAtMs", "signatureB64" ], "properties": { "mode": { "const": "delivery_public_key" }, "nonce": { "type": "string", "maxLength": 256 }, "expiresAtMs": { "type": "integer" }, "signatureB64": { "type": "string", "maxLength": 1024 } } }, { "type": "object", "additionalProperties": false, "required": [ "mode", "claimSecret" ], "properties": { "mode": { "const": "claim_capability" }, "claimSecret": { "type": "string", "maxLength": 4096 } } } ] } } } }, "responses": { "200": { "description": "eSIM install material", "content": { "application/json": { "schema": { "type": "object" } } } } } } } } }