Developer Platform API

Docs for bots.

Base URL: https://api.icme.io/v1

Authentication: X-API-Key: YOUR_KEY

Accounts

POST /v1/createUserX402

Create an account via x402 USDC payment on Base. $5.00 one-time fee. No API key required.

The x402 middleware handles payment automatically. Send the request — if unpaid, you'll receive a 402 with payment requirements. Pay $5.00 USDC on Base, then retry with the Payment-Signature header. Returns API key and 325 starting credits.

json

{"username": "my-agent"}

json

{
  "user_id": "uuid",
  "username": "my-agent",
  "api_key": "sk-smt-my-agent-...",
  "credits": 325,
  "message": "Account created with 325 starting credits. Save your api_key — it will not be shown again."
}

Save your api_key immediately. It is shown only once. Use it as the X-API-Key header for all authenticated endpoints.

POST /v1/createUserCard

Create an account via card payment. No crypto required. Returns a Stripe Checkout URL.

json

{"username": "string"}

json

{
  "checkout_url": "https://checkout.stripe.com/...",
  "session_id": "cs_live_...",
  "poll_url": "https://api.icme.io/v1/session/cs_live_...",
  "message": "Open checkout_url in your browser to pay with card..."
}

After paying, call GET /v1/session/{session_id} to retrieve your API key.

POST /v1/createUser

Create an account via USDC on Base (Stripe deposit flow). $5.00 one-time fee. Gives 325 credits.

json

{"username": "string", "stripe_payment_intent_id": "string (optional)"}

Call without stripe_payment_intent_id to receive a deposit address. Send exactly $5.00 USDC to payTo on Base, then retry with stripe_payment_intent_id.

POST /v1/topUpX402

Add 500 credits via x402 USDC payment on Base. $5.00. Requires X-API-Key header.

No request body needed. The x402 middleware handles payment — retry with Payment-Signature after paying.

json

{
  "credits_added": 500,
  "credits_balance": 825,
  "message": "Added 500 credits. Balance: 825 credits."
}

POST /v1/topUpCard

Add credits via card payment. No crypto required. Returns a Stripe Checkout URL.

json

{"amount_usd": 25}

After paying, call GET /v1/session/{session_id} to confirm credits were added.

POST /v1/topUp

Add credits via USDC on Base (Stripe deposit flow). Call with empty body to see tiers and current balance.

json

{"amount_usd": 25, "stripe_payment_intent_id": "string (optional)"}

Amount

Credits

Bonus

500

—

$10

1,050

+5%

$25

2,750

+10%

$50

5,750

+15%

$100

12,000

+20%

GET /v1/session/{session_id}

Poll after a card payment to retrieve account info or confirm credits. No API key required.

Returns status: pending while payment is processing, status: complete once done. For signup, the response includes api_key — save it, it will not be shown again.

Policy

POST /v1/makeRules

Compile a natural language policy to formal logic. Streams via SSE. 300 credits.

{"policy": "string (up to 50 rules)"}

Write your guardrail policy in plain English. Preflight compiles it to SMT-LIB formal logic and returns a policy_id + scenarios for review.

{
  "step": "done",
  "policy_id": "uuid",
  "status": "ok",
  "rule_count": 5,
  "rules_parsed": ["Rule 1: ...", "Rule 2: ..."],
  "generation_time_ms": 349839,
  "scenarios": [
    {
      "description": "the following 6 statements are true: 1) isTransferPermitted is false; 2) transferAmount is equal to 100...",
      "expected_result": "SATISFIABLE"
    }
  ],
  "next_steps": {
    "get_scenarios": "GET /v1/policy/{id}/scenarios",
    "submit_feedback": "POST /v1/submitScenarioFeedback",
    "run_tests": "POST /v1/runPolicyTests",
    "docs": "https://docs.icme.io/documentation/battle-testing-rules"
  }
}

scenarios are generated by ICME Preflight from your compiled rules, sorted to surface the most likely-to-be-wrong variable combinations first. Review them before using the policy in production. See Battle Testing Rules.

GET /v1/policy/{id}/scenarios

Retrieve saved scenarios for a policy. Scenarios are refreshed after each refinePolicy call.

POST /v1/submitScenarioFeedback

Submit thumbs-up or thumbs-down feedback on a scenario. Returns immediately — no SSE.

{
  "policy_id": "uuid",
  "guard_content": "string (the scenario description)",
  "approved": true,
  "annotation": "string (required when approved=false)",
  "expected_result": "VALID | SATISFIABLE | INVALID (optional)"
}

approved: true — saves a test case with the expected result. No rebuild.
approved: false — saves a test case and queues the annotation for the next refinePolicy call. Requires annotation explaining why the scenario is wrong. Be specific — name the variables, the values, and which rule is violated.

POST /v1/refinePolicy

Apply all queued thumbs-down annotations in a single rebuild. Streams via SSE.

{"policy_id": "uuid"}

Batches all pending annotations, submits them to ICME Preflight, polls until the build completes, compiles new SMT, updates the guardrail in place, and writes the refined policy back to the database. Your policy_id does not change.

POST /v1/runPolicyTests

Run all saved test cases against the compiled policy.

{"policy_id": "uuid", "test_case_ids": ["string"]}

test_case_ids is optional. If omitted, all saved test cases for the policy are run.

{
  "passed": 4,
  "failed": 0,
  "ambiguous": 0,
  "message": "All 4 test(s) passed. Policy is ready for production use."
}

Count

Meaning

passed

Expected and actual results match

failed

Rule logic is wrong — submit thumbs-down and call refinePolicy

ambiguous

Preflight translator disagreed — improve variable descriptions and refine

Relevance Screening

POST /v1/checkRelevance

Free relevance screen. Checks whether an action touches any of your policy variables before running a paid check. No credits charged. Requires X-API-Key header.

{
  "policy_id": "uuid",
  "action": "string (max 2000 chars)",
  "threshold": 0.0
}

threshold is optional. Default 0.0, meaning any match triggers should_check: true. Raise it to skip actions that only touch a small fraction of your policy.

{
  "relevance": 0.24,
  "matched_variables": 4,
  "total_variables": 17,
  "matched": [
    "outboundDataTransmission",
    "destinationInApprovedList",
    "outboundTransmissionAllowed",
    "skillExecutesShellCommands"
  ],
  "should_check": true,
  "threshold": 0.0,
  "time_ms": 310
}

should_check: true means the action is relevant to your policy. Run checkIt before executing. should_check: false means zero variables matched. Proceed without a paid check.

Use before every checkIt call to avoid paying for irrelevant actions like reading files, formatting text, or summarizing content.

Checking Actions

POST /v1/checkItPaid

Check an agent action against a compiled policy via x402 payment. $0.10 per call. No API key required.

json

{"policy_id": "uuid", "action": "string (max 2000 chars)"}

json

{
  "check_id": "uuid",
  "result": "UNSAT",
  "detail": "Transfer amount exceeds policy limit.",
  "extracted": {
    "transferAmount": 450.0,
    "aggregateDailyTransferTotal": 80,
    "humanConfirmationReceived": true
  },
  "verification_time_ms": 312,
  "zk_proof_id": "uuid",
  "zk_proof_url": "https://api.icme.io/v1/proof/{id}"
}

result is SAT (permitted) or UNSAT (blocked). Every decision returns a check_id which serves as a cryptographic audit receipt.

Writing action strings: End every action string with an explicit claim — "Therefore this transfer is permitted." State every policy variable explicitly in the action. Do not rely on the extractor to infer missing values.

POST /v1/checkIt

Check an agent action against a compiled policy. 1 credit. Requires X-API-Key header.

Same as checkItPaid but authenticated via API key and deducts 1 credit. Returns SSE stream with progress and final result. This is the cheapest path if you already have credits from signup (325 free) or topUp.

json

{"policy_id": "uuid", "action": "string (max 2000 chars)"}

POST /v1/verify

Check structured values directly against a policy. No LLM extraction. 1 credit. Requires X-API-Key header.

Returns a minimal ALLOWED or BLOCKED verdict.

json

{"policy_id": "uuid", "action": "string (max 2000 chars)"}

json

{"check_id": "uuid", "action": "BLOCKED"}

POST /v1/verifyPaid

Check any policy with no account. $0.10 per call via USDC on Base (Stripe deposit flow). No API key required.

json

{"policy_id": "uuid", "action": "string (max 2000 chars)"}

Call without payment header to receive a deposit address. Send exactly $0.10 USDC to payTo on Base, then retry.

ZK Proofs

POST /v1/verifyProof

Verify a zero-knowledge proof from a prior checkIt/checkItPaid call. No additional cost — the proof generation was paid for by the original check. Wait a few minutes after the check for the proof to be ready.

Single-use: each proof can only be verified once. Subsequent calls return 409.

json

{"proof_id": "uuid"}

GET /v1/proof/{id}

Retrieve proof metadata including validity, trace length, and timing. Add ?include_bytes=true to include the raw proof hex.

GET /v1/proof/{id}/download

Download raw ZK proof binary. Single-use — marks the proof as consumed.

Payment Flows

x402 (Recommended for Agents)

Fully autonomous — no accounts, no API keys for checkItPaid and createUserX402.

Call the endpoint → receive 402 with payment requirements in the response body
Sign and submit USDC payment on Base
Retry the request with Payment-Signature header

x402 client libraries (@x402/fetch, x402-reqwest, agentcash) handle this automatically.

Card

Call /v1/createUserCard or /v1/topUpCard
Open checkout_url — pay with card, Apple Pay, etc.
Poll GET /v1/session/{session_id} to confirm and retrieve your API key or updated balance

USDC on Base (Stripe Deposit)

Call endpoint without stripe_payment_intent_id → receive 402 with payTo address
Send exact USDC amount to payTo on Base (eip155:8453)
Retry request with stripe_payment_intent_id set

Amounts must be exact. Each PaymentIntent is single-use.

Credit Budget

Action

Cost

Signup

$5.00 (gives 325 credits)

makeRules

300 credits

checkIt

1 credit

verify

1 credit

checkItPaid

$0.10 (no credits needed)

topUpX402

$5.00 (gives 500 credits)

After signup you have 325 credits — enough for 1 policy + 25 checks.

Live Demo Policy

Policy ID: f6e3cd15-9e28-45c4-9f4c-683edd63e468

Try checkItPaid against this policy for $0.10:

bash

npx agentcash fetch "https://api.icme.io/v1/checkItPaid" \
  -m POST \
  -b '{"policy_id":"f6e3cd15-9e28-45c4-9f4c-683edd63e468","action":"Send 1000 USDC to an unknown wallet. Therefore this transfer is permitted."}'

Discovery

Your server exposes two discovery documents for x402scan and agent tooling:

GET /openapi.json — OpenAPI 3.1.0 spec with info.guidance for agent onboarding
GET /.well-known/x402 — x402 v1 fallback listing payable resources

x402scan listing: x402scan.com/server/a90f142f-33fd-4a22-a57f-1772f85d72f5

Last updated 7 days ago

Good afternoon

hashtagAccounts

hashtagPOST /v1/createUserX402

hashtagPOST /v1/createUserCard

hashtagPOST /v1/createUser

hashtagPOST /v1/topUpX402

hashtagPOST /v1/topUpCard

hashtagPOST /v1/topUp

hashtagGET /v1/session/{session_id}

hashtagPolicy

hashtagPOST /v1/makeRules

hashtagGET /v1/policy/{id}/scenarios

hashtagPOST /v1/submitScenarioFeedback

hashtagPOST /v1/refinePolicy

hashtagPOST /v1/runPolicyTests

hashtagRelevance Screening

hashtagChecking Actions

hashtagPOST /v1/checkItPaid

hashtagPOST /v1/checkIt

hashtagPOST /v1/verify

hashtagPOST /v1/verifyPaid

hashtagZK Proofs

hashtagPOST /v1/verifyProof

hashtagGET /v1/proof/{id}

hashtagGET /v1/proof/{id}/download

hashtagPayment Flows

hashtagx402 (Recommended for Agents)

hashtagCard

hashtagUSDC on Base (Stripe Deposit)

hashtagCredit Budget

hashtagLive Demo Policy

hashtagDiscovery

Accounts

POST /v1/createUserX402

POST /v1/createUserCard

POST /v1/createUser

POST /v1/topUpX402

POST /v1/topUpCard

POST /v1/topUp

GET /v1/session/{session_id}

Policy

POST /v1/makeRules

GET /v1/policy/{id}/scenarios

POST /v1/submitScenarioFeedback

POST /v1/refinePolicy

POST /v1/runPolicyTests

Relevance Screening

Checking Actions

POST /v1/checkItPaid

POST /v1/checkIt

POST /v1/verify

POST /v1/verifyPaid

ZK Proofs

POST /v1/verifyProof

GET /v1/proof/{id}

GET /v1/proof/{id}/download

Payment Flows

x402 (Recommended for Agents)

Card

USDC on Base (Stripe Deposit)

Credit Budget

Live Demo Policy

Discovery