# 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": "Too many intent requests. Retry later.",
  "code": "rate_limited",
  "correlation_id": "req_3f5b42e0f1a9e8c1"
}
```

## 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",
  "session_token": "9f2c50f8a0f5d8d0b0efc4fa665e4032f31bb0c4c4f31b8c",
  "session_expires_at": "2026-03-18T07:31:12Z"
}
```

Response headers also include:

1. `X-Edut-Session: <session_token>`
2. `X-Edut-Session-Expires-At: <session_expires_at>`

Error (`400` intent expired):

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

## 3) `POST /secret/wallet/session/refresh`

Request:

Headers:

1. `Authorization: Bearer <session_token>` (or `X-Edut-Session`)

```json
{
  "wallet": "0x3ea6cbf98d23e2cf7b6f4f9bb1fb4f50b710f2d5"
}
```

Success (`200`):

```json
{
  "status": "session_refreshed",
  "wallet": "0x3ea6cbf98d23e2cf7b6f4f9bb1fb4f50b710f2d5",
  "session_token": "f9bc20f15ecf7fd53f1f4ba8ca774564a1098e6ed9db6f0f",
  "session_expires_at": "2026-03-18T07:42:10Z"
}
```

Error (`401` missing/expired token):

```json
{
  "error": "wallet session required",
  "code": "wallet_session_required"
}
```

## 4) `POST /secret/wallet/session/revoke`

Request:

Headers:

1. `Authorization: Bearer <session_token>` (or `X-Edut-Session`)

```json
{
  "wallet": "0x3ea6cbf98d23e2cf7b6f4f9bb1fb4f50b710f2d5"
}
```

Success (`200`):

```json
{
  "status": "session_revoked",
  "wallet": "0x3ea6cbf98d23e2cf7b6f4f9bb1fb4f50b710f2d5",
  "revoked_at": "2026-02-17T07:34:02Z"
}
```

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

Request:

```json
{
  "designation_code": "0217073045482",
  "address": "0x3ea6cbf98d23e2cf7b6f4f9bb1fb4f50b710f2d5",
  "chain_id": 8453,
  "payer_wallet": "0x2299547f6fA9A8f9b6d9aEA9F9D8A4B53C8A0e11",
  "payer_proof": "0xowner-signed-proof",
  "sponsor_org_root_id": "org_company_a"
}
```

Success (`200`):

```json
{
  "quote_id": "mq_01HZZX4F8VQXJ6A57R8P3SCB2W",
  "chain_id": 8453,
  "currency": "USDC",
  "amount_atomic": "100000000",
  "decimals": 6,
  "cost_envelope": {
    "version": "edut.quote_cost_envelope.v1",
    "checkout_currency": "USDC",
    "checkout_decimals": 6,
    "checkout_total_atomic": "100000000",
    "checkout_total": "100",
    "provider_fee_policy": "edut_absorbed",
    "provider_fee_included": true,
    "provider_fee_estimate_status": "absorbed_by_edut",
    "provider_fee_estimate_atomic": "0",
    "network_fee_policy": "payer_wallet_pays_chain_gas",
    "network_fee_currency": "ETH",
    "network_fee_estimate_status": "wallet_estimate_required",
    "network_fee_estimate_atomic": "0"
  },
  "deadline": "2026-02-17T07:36:12Z",
  "contract_address": "0x1111111111111111111111111111111111111111",
  "method": "mintMembership(address)",
  "calldata": "0xdeadbeef",
  "value": "0x0",
  "owner_wallet": "0x3ea6cbf98d23e2cf7b6f4f9bb1fb4f50b710f2d5",
  "payer_wallet": "0x2299547f6fA9A8f9b6d9aEA9F9D8A4B53C8A0e11",
  "sponsorship_mode": "sponsored_company",
  "sponsor_org_root_id": "org_company_a",
  "tx": {
    "from": "0x2299547f6fA9A8f9b6d9aEA9F9D8A4B53C8A0e11",
    "to": "0x1111111111111111111111111111111111111111",
    "data": "0xdeadbeef",
    "value": "0x0"
  }
}
```

Error (`403` not verified):

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

Error (`403` distinct payer without proof):

```json
{
  "error": "distinct payer requires ownership proof",
  "code": "request_failed"
}
```

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

Request:

```json
{
  "designation_code": "0217073045482",
  "quote_id": "mq_01HZZX4F8VQXJ6A57R8P3SCB2W",
  "tx_hash": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "address": "0x3ea6cbf98d23e2cf7b6f4f9bb1fb4f50b710f2d5",
  "chain_id": 8453,
  "identity_assurance_level": "onramp_attested",
  "identity_attested_by": "moonpay",
  "identity_attestation_id": "mp_session_01JAA..."
}
```

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",
  "identity_assurance_level": "onramp_attested",
  "identity_attested_by": "moonpay",
  "identity_attestation_id": "mp_session_01JAA..."
}
```

Error (`400` tx mismatch):

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

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

Request by wallet:

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

Success (`200`):

```json
{
  "status": "active",
  "wallet": "0x3ea6cbf98d23e2cf7b6f4f9bb1fb4f50b710f2d5",
  "designation_code": "0217073045482",
  "identity_assurance_level": "onramp_attested",
  "identity_attested_by": "moonpay",
  "identity_attestation_id": "mp_session_01JAA..."
}
```

Error (`400` missing selectors):

```json
{
  "error": "Provide wallet or designation_code.",
  "code": "missing_selector",
  "correlation_id": "req_f23618fdd4479b89"
}
```