One decision call, before your agent pays.

Your first decision, in one command.

curl -s -X POST https://api.fidren.net/v1/decision \
  -H 'content-type: application/json' \
  -d '{
    "address": "0xf1d0000000000000000000000000000000000001",
    "chain": "base",
    "amount_cents": 5000,
    "currency": "USD"
  }'

That address is a documentation example with no history, so the answer is an honest REVIEW: Fidren says it does not know this counterparty rather than guessing. Change the address to one you care about and run it again.

{
  "decision_id": "dec_a3b2fb82ab9e56577e3e8e23a37826e2",
  "decision": "REVIEW",
  "trust_score": 50,
  "exposure_level": 2,
  "confidence": "LOW",
  "recommended_limit_cents": 10000,
  "requested_amount_cents": 5000,
  "amount_status": "WITHIN_SUPPORTED_EXPOSURE",
  "payment_action": "REVIEW",
  "authorized_limit_cents": 0,
  "currency": "USD",
  "reasons": [
    "Insufficient observations to assess this counterparty; treat as unknown, not as adverse"
  ],
  "reason_codes": [
    { "code": "INSUFFICIENT_OBSERVATIONS" }
  ],
  "evidence": [
    { "code": "NO_HISTORY", "detail": "Insufficient observations to establish a track record", "value": 0 },
    { "code": "NEW_ADDRESS", "detail": "Address first observed 0 day(s) ago", "value": 0 }
  ],
  "evaluated_at": "2026-09-17T17:44:20.072Z",
  "disputed": false,
  "notification": "UNREACHABLE",
  "scoring_model_version": "score-v1.1.0",
  "decision_policy_version": "policy-v1.7.0"
}

Your decision_id and evaluated_at will differ. Everything else is the shape you receive.

What each field means

decision

What to do about this counterparty. One of five actions, not a score for you to interpret.

trust_score · confidence

How the record reads, and how much record there is. A low confidence score is not a bad counterparty — it is a thin one.

recommended_limit_cents

The exposure the evidence supports, independent of what you asked for.

amount_status · payment_action

These answer your amount, not the counterparty. The same party can be worth paying $50 and not worth paying $50,000, and these two fields are where that difference appears.

reasons · evidence

Why, in terms you can quote to whoever asks. Evidence carries codes and values, not prose alone.

evaluated_at

When the decision was made. Not the timestamp of the newest observation behind it.

scoring_model_version · decision_policy_version

Which model and which policy produced this answer, so an old decision stays re-derivable.

Same counterparty. Same evidence. Different exposure.

Same counterparty. Same evidence. Different exposure. Different payment decision. The trust score and the confidence are identical in both calls — only the amount moved.

100 free decisions per day, per IP.

The allowance is counted against the network origin Fidren observes for your request, and resets at 00:00 UTC. That origin comes from the connection itself, not from a header you can set — so it cannot be reset by changing one. Callers sharing one outbound IP, such as a team behind a single gateway, share one allowance. There is no signup: the first call is the first step, rather than a signup or a conversation with us.

What does not spend an allowance

• A malformed request. A 400 costs you nothing.
• A failure on our side. If Fidren cannot serve a decision, you are not charged an allowance for it.
• A request the rate limiter refused — see below.

An allowance is only spent when a decision is actually produced and delivered.

A rate limit is not the end of your free tier.

They protect different things and answer with different codes.

You can receive a 429 with your whole daily allowance still available. It means the burst was too fast, not that the free tier ran out.

When the free allowance runs out.

The next valid decision returns 402 Payment Required with the terms. Pay $0.01 USDC on Base, retry with the signature, and the decision comes back. No account.

Fidren-Payment-Mode: x402 is a Fidren access preference, not part of the x402 standard: it asks to be billed immediately instead of spending the free allowance.

One key, two accepted headers.

Both are accepted because agent frameworks differ in which headers they can set. Keys are 32 random bytes, base64url-encoded, prefixed fdrn_. The plaintext is generated server-side and shown once at creation; the database stores only a SHA-256 digest, so a leaked database yields no usable credential. A missing, malformed or unrecognised key all return the same 401 with the same message, so error text cannot be used to enumerate valid keys.

The request.

address required

The counterparty you would be paying. Any casing.

chain required

base or polygon. See the coverage note below — they are not equally served.

amount_cents required

The requested exposure, in USD-equivalent minor units. Integer, zero or more.

currency optional

USD, USDC or USDT. Defaults to USD. Echoed back and recorded; stablecoins are read 1:1 with USD.

service_identifier optional

A caller-side label for the service being paid. Yours, not interpreted.

The response.

All 17 fields below are present on every successful call.

The per-dimension scoring breakdown is not in the response and is not published anywhere. Naming which lever moves a score would turn a risk signal into a checklist for gaming it.

Every failure returns the same envelope.

The statuses below are the ones the contract documents. An unhandled fault returns the same shape with a 500, which the contract does not yet declare per route.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "…",
    "details": [{ "field": "amount_cents", "message": "…" }]
  },
  "request_id": "…"
}

details is present only when there is something field-level to report.

400 VALIDATION_ERROR

The body failed validation. details carries a { field, message } per problem.

401 UNAUTHORIZED

A presented key that is missing its value, malformed, or not recognised — all three answer identically, so error text cannot be used to enumerate keys. An anonymous caller whose allowance is spent is not refused: they receive a 402 with the terms. Sending no credential at all while you still have free allowance returns 200, not 401.

402 PAYMENT_REQUIRED

Payment is required for this call: either your free allowance is spent, or you sent Fidren-Payment-Mode: x402 to skip it. The PAYMENT-REQUIRED header carries the terms — exact scheme, USDC on Base, $0.01, valid for 300 seconds. Pay and retry the same request with PAYMENT-SIGNATURE to receive the decision. An invalid key is never charged: it is 401 and stops there.

404 NOT_FOUND

No such resource. Not returned by the decision endpoint.

409 CONFLICT

The report cannot be appended as submitted: an invalid lifecycle transition, a side already reported by a different address, or a chain that moved during the write. Only the last is worth retrying.

429 RATE_LIMITED

Over the per-minute allowance.

503 SERVICE_UNAVAILABLE

A dependency is unreachable. Safe to retry.

A per-minute allowance, reported on every response.

The bucket is chosen from a credential Fidren issued, never from the one in the request: a key the service does not recognise buys nothing and falls back to an allowance keyed on your network address. Authenticated callers draw a larger per-minute allowance than anonymous ones. The budget belongs to your organisation, not to an individual key: issuing a second key splits the same allowance rather than adding another one. Read the headers rather than hard-coding a number — the allowance is a deployment setting, not a published plan and not a per-key negotiation.

Over the limit you get 429 with the same error envelope as every other failure, and a Retry-After in whole seconds. The window is a fixed minute, so that value is the time left in the current one: wait it out and retry.

A request ID is not a decision ID.

Every response carries x-request-id, and every error body repeats it as request_id. Supply your own on the request header and it is honoured when it matches a conservative pattern; anything else is replaced with a generated value rather than sanitised, because a header is caller-controlled and log files are read by tools that interpret what they find.

Telling Fidren how it went.

After an operation concludes, either side may report the outcome to POST /v1/receipts. Each side keeps its own hash chain and the server computes the links, so a reporter cannot reorder or edit its own account afterwards. Three levels are worth keeping apart:

Recorded

Name a side and an address in the request body. It is stored, attributed to your API key — no other endpoint or parameter is involved.

Signed

Optionally, the report carries a personal_sign signature from the reporting address. Fetch the statement from POST /v1/receipts/signing-message, sign it, resubmit. A signature is verified and stored only if it verifies. Only a signature shows the reporter controls the address it names.

Corroborated

Automatic once both sides have separately called this endpoint and their signed accounts agree — nothing further to call.

A reported outcome is never treated as verified truth — the chain establishes integrity and ordering against the reporter, not that the account is accurate. Separately signed reports can still come from parties under common control. Why that limit exists, and what it does and does not prove, is on Security.