# Secret System API Examples (v1)

## 1) `POST /secret/wallet/intent`

Request:

```json
{
  "address": "0x3ea6cbf98d23e2cf7b6f4f9bb1fb4f50b710f2d5",
  "origin": "https://edut.ai",
  "locale": "en",
  "chain_id": 8453
}
```

Success (`200`):

```json
{
  "intent_id": "wi_01HZZX2Q8R0FQFQ6B1VQ1N2P9J",
  "designation_code": "0217073045482",
  "display_token": "0217-0730-4548-2",
  "nonce": "47f43f70d1288d4e",
  "issued_at": "2026-02-17T07:30:45Z",
  "expires_at": "2026-02-17T07:35:45Z",
  "domain_name": "EDUT Designation",
  "chain_id": 8453,
  "verifying_contract": "0x0000000000000000000000000000000000000000"
}
```

Error (`429` rate limited):

```json
{
  "error": "rate_limited",
  "message": "Too many intent requests. Retry later."
}
```

## 2) `POST /secret/wallet/verify`

Request:

```json
{
  "intent_id": "wi_01HZZX2Q8R0FQFQ6B1VQ1N2P9J",
  "address": "0x3ea6cbf98d23e2cf7b6f4f9bb1fb4f50b710f2d5",
  "chain_id": 8453,
  "signature": "0xabcdef..."
}
```

Success (`200`):

```json
{
  "status": "signature_verified",
  "designation_code": "0217073045482",
  "display_token": "0217-0730-4548-2",
  "verified_at": "2026-02-17T07:31:12Z"
}
```

Error (`400` intent expired):

```json
{
  "error": "intent_expired",
  "message": "Intent has expired. Request a new intent."
}
```

## 3) `POST /secret/membership/quote`

Request:

```json
{
  "designation_code": "0217073045482",
  "address": "0x3ea6cbf98d23e2cf7b6f4f9bb1fb4f50b710f2d5",
  "chain_id": 8453
}
```

Success (`200`):

```json
{
  "quote_id": "mq_01HZZX4F8VQXJ6A57R8P3SCB2W",
  "chain_id": 8453,
  "currency": "USDC",
  "amount": "5.00",
  "amount_atomic": "5000000",
  "decimals": 6,
  "deadline": "2026-02-17T07:36:12Z",
  "contract_address": "0x1111111111111111111111111111111111111111",
  "method": "mintMembership",
  "calldata": "0xdeadbeef",
  "value": "0x0",
  "tx": {
    "to": "0x1111111111111111111111111111111111111111",
    "data": "0xdeadbeef",
    "value": "0x0"
  }
}
```

Error (`403` not verified):

```json
{
  "error": "signature_not_verified",
  "message": "Signature verification is required before quote issuance."
}
```

## 4) `POST /secret/membership/confirm`

Request:

```json
{
  "designation_code": "0217073045482",
  "quote_id": "mq_01HZZX4F8VQXJ6A57R8P3SCB2W",
  "tx_hash": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "address": "0x3ea6cbf98d23e2cf7b6f4f9bb1fb4f50b710f2d5",
  "chain_id": 8453
}
```

Success (`200`):

```json
{
  "status": "membership_active",
  "designation_code": "0217073045482",
  "display_token": "0217-0730-4548-2",
  "tx_hash": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "activated_at": "2026-02-17T07:33:09Z"
}
```

Error (`400` tx mismatch):

```json
{
  "error": "tx_mismatch",
  "message": "Transaction amount or destination does not match quote policy."
}
```

## 5) `GET /secret/membership/status`

Request by wallet:

`GET /secret/membership/status?wallet=0x3ea6cbf98d23e2cf7b6f4f9bb1fb4f50b710f2d5`

Success (`200`):

```json
{
  "status": "active",
  "wallet": "0x3ea6cbf98d23e2cf7b6f4f9bb1fb4f50b710f2d5",
  "designation_code": "0217073045482"
}
```

Error (`400` missing selectors):

```json
{
  "error": "missing_selector",
  "message": "Provide wallet or designation_code."
}
```