# External Tester Quickstart

Use this when you want to test the hosted Cortex Base Sepolia deployment without cloning the repo or getting database access.

Hosted surfaces:

- Web app: `https://cortex.projectaegis.ai`
- API: `https://cortex-api.projectaegis.ai`
- Explorer: `https://sepolia.basescan.org`
- Base Sepolia faucets: `https://docs.base.org/base-chain/network-information/network-faucets`

## 1. Prepare a Wallet

Use MetaMask, Rabby, Coinbase Smart Wallet, or another EIP-1193 wallet.

1. Add or switch to Base Sepolia.
2. Fund the wallet with a small amount of Base Sepolia ETH. The direct-transfer walkthrough only needs testnet ETH for gas and payment.
3. Open `https://cortex.projectaegis.ai/onboarding` and connect the wallet.

## 2. Request a Hosted API Key

Hosted document writes require `X-Cortex-Api-Key`. The web app can request one for you:

1. In `/onboarding`, use the **Hosted API key** panel.
2. Click **Request key**.
3. Sign the wallet message. This does not submit a transaction or spend funds.
4. The key is stored in your browser local storage and is automatically sent on hosted document writes.

The signed message has this form:

```text
Cortex API key request
address: <your-lowercase-wallet-address>
issued_at: <unix-seconds>
```

For programmatic clients, call `POST https://cortex-api.projectaegis.ai/keys/request` with `address`, `issued_at`, `signature`, and optional `label`. Store the returned `api_key`; it is shown once.

## 3. Register a Merchant and Service

Open `https://cortex.projectaegis.ai/onboarding`.

1. Stay on **Merchant setup**.
2. Use the default merchant fields or enter your own.
3. Click **Publish profile**. This stores canonical merchant JSON in the hosted API.
4. Click **Register merchant** and confirm the transaction.
5. Switch to **Service**.
6. Use the defaults or enter your service details.
7. Click **Publish metadata**, **Publish catalog**, then **Register service**.

The dashboard can take a few seconds to show newly indexed records after each transaction.

## 4. Register an Agent and Policy

Still in `/onboarding`:

1. Switch to **Agent setup**.
2. In **Identity**, use the defaults and click **Register agent**.
3. In **Spending policy**, add a policy for the merchant you registered.
4. For the simplest path, use the zero address token (`0x0000000000000000000000000000000000000000`) and zero address facilitator.
5. Save the policy and confirm the wallet transaction.

## 5. Run a Purchase

Open `https://cortex.projectaegis.ai/purchase-simulator`.

1. Use **Registered context** to select your merchant, service, and agent.
2. The simulator defaults to **Direct transfer** with native testnet ETH. Keep that path for the first run.
3. Click **Commit quote** and confirm.
4. In **Pay & settle**, click **Send native ETH** and confirm.
5. Click **Record receipt** and confirm.
6. Click **Record fulfillment** and confirm.

After receipt and fulfillment transactions, wait roughly 5-10 seconds for the indexer before checking dashboards.

## 6. Verify

Use the dashboards:

- Protocol dashboard: `https://cortex.projectaegis.ai/dashboard`
- Merchant dashboard: `https://cortex.projectaegis.ai/dashboard/merchant`
- Agent dashboard: `https://cortex.projectaegis.ai/dashboard/agent`

Or use public read APIs:

```bash
export API_URL=https://cortex-api.projectaegis.ai
export ADDRESS=0xYourWallet

curl "$API_URL/merchants?owner=$ADDRESS&active=true"
curl "$API_URL/agents?owner=$ADDRESS&limit=50"
curl "$API_URL/receipts?agent=$ADDRESS&limit=50"
curl "$API_URL/analytics/commerce"
```

## Troubleshooting

- `401 API key required`: request a key from the **Hosted API key** panel, then retry the publish action.
- Wallet prompts on the wrong network: switch to Base Sepolia and retry.
- Merchant, service, receipt, or fulfillment is missing immediately after a transaction: wait a few seconds for the indexer and refresh.
- Empty merchant dropdown in the simulator: register a merchant/service first, or use the seeded demo merchants if available.
- Direct native payment is the lowest-friction path. ERC-20, facilitator, swap, and x402 flows may require token setup or additional approvals.