Elliptic Integration for Firms That Hold Funds Until the Screen Passes
Banks, payment firms and exchanges that bought Elliptic decide on its scores. Elliptic leaves them the AML API calls at a transfer, holds in their ledger and alerts in their case tool. Protofire builds those parts. Protofire engineers helped build the Gnosis Safe web app from 2019 to 2021.

Reviewed by Luis Medeiros, Field CTO at ProtofireLast reviewed: November 2026
On this page
Work shipped for 60+ networks and 95+ protocols, including
What your Elliptic integration must answer when a deposit arrives
After you sign with Elliptic, your Elliptic integration has to answer two questions for each deposit. Is the customer credited now, and what do the books show until Lens answers?
Elliptic screens wallets and transactions and runs monitoring. Elliptic logs each screen and alert with its risk factors in one Lens queue (Elliptic). Elliptic's AML API lets your firm control "what is submitted for analysis and when". So your firm decides which transfers wait for a Lens result, who reviews them and how its books show the hold.
An Elliptic answer comes in four forms. A null risk score means no risk rule fired, while a 0 means rules fired and scored 0 (AML API reference). A deposit analyzed "too close to the tip of the blockchain" comes back with predictive set to true. The picture of linked addresses for that deposit may be incomplete. A fresh hash can return 404 NotInBlockchain because Elliptic has not processed the hash yet. Release code that reads the score alone moves money it should hold.
Your compliance team owns the Lens risk rules and each threshold that holds funds. Protofire codes the checks that enforce those rules and thresholds. We work through a custody platform's connector or straight against the AML API.
Four gaps between an Elliptic score and your ledger
Elliptic scores what reaches it.Four gaps between Elliptic and your books decide whether the score becomes the right posting.
Custody connectors keep different parts of the result
Fireblocks drives its rules from the total score and stores a null as noRiskDetected. Fireblocks supports Elliptic on mainnet, so a testnet workspace cannot run Elliptic screens (Fireblocks). Dfns keeps the native 0 to 10 score untranslated (Dfns). Sumsub does not send transfers below Elliptic's minimum value for a chain (Sumsub). Protofire maps each connector's value to the rule your compliance team signed. So a null, a 0 and a predictive result each reach a named branch.
When Elliptic returns a 429 or no answer
The rule for a missing answer belongs to your firm, in the policy that compliance signs. A call over Elliptic's default limit gets HTTP 429 (Elliptic). On Dfns, a prescreening policy with skipEllipticFailure set to true lets a transfer pass on "timeout, rate limiting, any error" (Dfns). Protofire keeps each unanswered transfer in a named state. The state is held, queued for a retry within the rate limit, or waiting for a rescreen. Elliptic sells Fast Track Monitoring as "a back up screening option" (Elliptic, November 2026). Fast Track Monitoring runs on Elliptic's default risk rules (Elliptic), so its scores need their own thresholds.
Rescreens and webhooks that arrive after the money moved
Switching on Continuous Monitoring takes "signing a contract amendment" and a Lens Admin (Elliptic, August 2026). System Rescreening retries an analysis that ended in error, daily for three days (Elliptic). The money has usually moved by then. So the result feeds a case, and the ledger acts on funds the firm still holds. Elliptic's June 2026 notice renames the webhook event types. Elliptic calls the rename "a breaking change if you currently route logic based on event.type" (Elliptic, June 2026). Elliptic's webhook docs describe no redelivery policy (Elliptic). So the receiver that Protofire builds dedupes on the screening ID, and a nightly sweep catches a missed event.
Tracing which Elliptic rule version decided a transfer
Each Elliptic result names the rules that fired, using a rule_history_id that "links all versions of a risk rule" (AML API reference). The version API returns each rule's version number and an is_current flag (v3 reference). Continuous Monitoring rescreens "against your existing risk rules" (Elliptic). So a tightened rule raises alerts on transfers that cleared months ago. Protofire stores the rule version with each decision, so a reviewer sees the exact rule a year later.
[...] virtual currency companies may consider conducting a historic lookback of transactional activity after OFAC lists a virtual currency address on the SDN List to identify connections to the listed address.
Elliptic API limits, webhooks and chain coverage
- Default rate limits
- Elliptic allows 500 requests a minute overall and 15 a second on the synchronous analysis endpoints. Batch endpoints allow 4 a second. These defaults apply "unless agreed otherwise" (Elliptic). A batch takes up to 100 items (batch reference).
- Webhooks
- Elliptic webhooks have two event types, transaction_screening.completed and wallet_screening.completed. Each event is a signed CloudEvents envelope, and its event id is the screening ID (Elliptic).
- Coverage
- The Lens page lists "60+ blockchains and 250+ bridges" (Elliptic). The full support list is behind the customer login.
Checked November 2026 against Elliptic's documentation.
What Protofire builds in an Elliptic integration
Deposits credited after Elliptic has answered
Protofire builds the screening service that calls the AML API at each transfer. The service applies the thresholds that your compliance team signed. Until the screen passes, the customer sees a pending deposit, and the amount is recorded on a suspense line.
Ledger holds that match the custody transfer
The ledger shows a hold when custody shows the transfer. The hold ends as a release, a return or a blocked-funds position. Protofire posts each branch together with your finance team. Each posting is keyed on the Elliptic analysis ID, recorded next to the custody transfer ID.
Elliptic alerts in your existing case tool
A rescreen alert opens as a case next to your fiat alerts, with the score and the rule IDs. When your analyst records a decision, the decision goes back to Lens as escalated or closed. So both systems show one status. The write-back uses an API key that your firm holds.
A retry queue for transfers with no answer
Each unanswered transfer has a named state and a person who works it. Protofire builds the retry queue and a count of transfers still waiting on Elliptic. Your team reads that count, or Protofire's managed onchain operations service can watch it.
A write-once archive of each decision
Each request, response, rule version and decision is stored in a write-once archive, so a reviewer can open the file a year later. Protofire adds reports on hold times, null results and transfers with no answer.
New tokens checked before they are listed
A new token is tested against Elliptic's support list and Elliptic's minimum value per chain before the token is listed.
Decisions your compliance team keeps after Elliptic scores a transfer
Elliptic runs the screening and returns the scores, and your firm decides on them.A score does not say whether the transfer reached the screen, what to hold or whom to report to.
Your compliance team keeps these decisions:
- the Lens risk rules
- the thresholds that hold funds
- the rule for a transfer with no answer
- each release decision
- each report to your FIU
Protofire codes the rules that your compliance team signs.
Our record: the Gnosis Safe web app and a MiCA blueprint
Protofire's public record here is in software where a transfer waits for a decision.The record is also in a published map of the vendors that a new CASP rents. Protofire's record applies here. An Elliptic integration is also software built around a check that others decide.
Gnosis Safe web app, 2019 to 2021
Protofire engineers helped build the Gnosis Safe web app from 2019 to 2021. In the Gnosis Safe web app, an outgoing transfer waits until enough owners approve it.
Day-One MiCA Compliance Stack blueprint
Protofire's Day-One MiCA Compliance Stack for CASPs lists Elliptic as one source of the screening risk data that a new CASP rents. The blueprint sets out the routing layer and the record store that the CASP builds around those vendors.
Elliptic project phases, from setup review to handover
- Step 1
An engineer reads your Elliptic setup
The engineer reads which Elliptic products your contract includes and your Lens risk rules. The engineer also reads your connector settings and the ledger where a held deposit is booked. A written proposal with findings and a plan in phases follows. - Step 2
Screening calls and ledger holds come first
The screening calls and the ledger holds are built together, so no deposit is credited before its result is in. Test runs use known clean and flagged addresses. - Step 3
Alerts, archive and retry queue come next
The webhook receiver, case routing and Lens write-back come next. The archive and the retry queue arrive in the same phase. Test and production each get their own webhook configuration (Elliptic). - Step 4
Your firm owns the code and the API key
The code, configuration and runbooks are yours. Your staff generate the API key in Elliptic Workspace Settings (Elliptic).
How an Elliptic project with Protofire starts
You send three things: the Elliptic products in your contract, your current Lens risk rules and where a held deposit is booked today.Protofire's proposal lists each AML API call and webhook that we would build, with its phase. The services call Elliptic with an API key that your staff generate in Workspace Settings. Your staff keep that key in your vault. The scope under which Protofire operates the services lists the write calls they make, such as Lens workflow status updates. The terms below apply to each phase, as set out on how we work.
- Proposal
- In writing, one business day after the discovery call: findings, a plan in phases and the first step we recommend.
- Price
- Fixed per phase when you commission it, against written acceptance criteria. Overruns inside them are ours to absorb, invoices follow delivered milestones, and you can stop at any phase boundary. Anything we operate after launch is priced in the proposal as its own recurring line, with the notice to end it.
- Ownership
- Code we write for you, contracts, the keys and credentials this work creates and the accounts your infrastructure runs in are yours by contract, within the license of any third-party software involved. Keys that a custody platform or a staking provider holds under its own key model stay with it under your contract; every other custody key stays with you or the custodian you appoint. Where the scope places something on servers we rent, it says what moves to you and when. An NDA is available from your first message, and we sign a data processing agreement (DPA) together with it.
- After launch
- Delivery closes with a hypercare window and a defect warranty, with their terms written into the proposal. A service we operate continues under its written scope until that scope ends.
- Access
- Read-only by default. A role that can start requests only if your written scope names one; never a signer, approver, administrator, key holder or recovery role on your contracts, wallets or custody platform. Services we build call each platform on credentials your staff issue and keep in your vault. Anything that approves or moves funds runs in your environment, and a scope under which we operate a service lists every write call it makes. Where the scope has us operate nodes, validators, monitors, explorers or indexers, it names the role and any key we hold on those servers, and in your own cloud account you can remove it.
- Licenses
- Protofire is an engineering firm and holds no financial or crypto-asset license; licensed activity stays with you and your providers.
How we work shows a worked proposal.
When a custody connector and Lens are enough
You can skip an integration project when a custody connector screens your transfers and your analysts work alerts in Lens.
- One custody platform screens your transfers, and no hold has to be posted to your ledger. Dfns, for example, screens "in both directions" (Dfns).
- Your volume is small enough to screen by hand in Lens (Elliptic).
- Your open question is risk appetite, policy or training. Those questions belong to your compliance advisers.
- Your project joins several vendors besides Elliptic. Protofire's compliance integration service covers KYC, screening and Travel Rule vendors as one decision.
Protofire builds the systems around the screening vendor. Protofire gives no legal opinion and takes no compliance decision. We make no promise about what screening catches or blocks. We hold no financial or crypto-asset license.
FAQ
What is an Elliptic integration?
Who can build an Elliptic integration for a bank, a payment firm or an exchange?
What does a null Elliptic risk score mean?
Should a withdrawal call Elliptic synchronously or in a batch?
Did the move from Navigator to Lens break API integrations?
What customer data reaches Elliptic?
Get a proposal
Tell us what you are building. An engineer reads it, we have a short call, and the written proposal follows within one business day.
