Build a Custom API Approver

Use an API User and webhooks to build a custom API Approver that performs automated validation checks on Fordefi transactions.

An API Approver extends Fordefi's built-in policy engine with your own custom business logic. While Fordefi policies cover many common and advanced approval conditions, you may have organization-specific requirements that aren't natively supported. An API Approver lets you enforce those custom rules programmatically before a transaction is approved.

The API Approver is chain agnostic and can inspect transaction payloads on any supported blockchain. For example, you can use it to:

• Inspect the parameters of a Solana program instruction to verify that it invokes an approved program with the expected accounts and arguments.
• Parse and validate any field in EVM EIP-712 messages.
• Verify that the recipient of a bridge transaction is on an approved whitelist.
• Restrict transactions to approved methods on a Solana program.
• Validate transaction data against internal systems or compliance databases.
• Enforce custom business rules that are unique to your organization.

To run this setup you will need to:

• Create an API User with the Trader role and save its access tokens. Learn more.

  The example that follows, below, uses an API User named Validator Bot, which will serve as our custom API Approver and enforce the validation rules you define.

• Set up a modified webhook server that will receive events from Fordefi. Learn more.

  The instructions below use a modified server designed to enforce a number of custom validation rules. For example, it can inspect the parameters of a Solana program instruction, validate calldata or EIP-712 messages in EVM transactions, verify that a bridge destination is whitelisted, or implement any other organization-specific approval logic.

Since the API Approver has the authority to approve or abort transactions, it's critical to lock down both the webhook endpoint it exposes and the API User credentials it uses.

Verify webhook signatures. Every webhook that Fordefi sends includes a signature header. You should verify this signature against Fordefi's public key to confirm that the payload genuinely originated from Fordefi and that it hasn't been tampered with. See the webhook validation documentation for the public key and implementation details.

Whitelist Fordefi's IP. Restrict inbound traffic to your API Approver server by whitelisting Fordefi's NAT address:

54.243.103.88

This ensures that only Fordefi's infrastructure can reach your webhook endpoint. Any requests originating from other IPs can be dropped at the firewall or load balancer level before they ever hit your application.

Restrict the API User to trusted outbound IPs. Configure the API User used by your API Approver to only accept API requests originating from your Approver's static outbound IP address(es). This limits the impact of a leaked API token by preventing it from being used outside your trusted infrastructure. See Edit whitelisted IPs for an API User for configuration instructions.

Combining webhook signature verification, inbound IP whitelisting and API User IP restrictions provides defense in depth against spoofed webhook requests and unauthorized use of your API credentials.

1. Create a policy with a single-set approval quorum including Validator Bot as your custom API Approver:

   

   This quorum implements the following logic: The API Approver only approves transactions that pass your custom validation checks. If validation fails, it automatically aborts the transaction using the /transactions/{tx_id}/abort endpoint documented here.

   Note: You can add additional approval sets, including human approvers, to the quorum. In this example, however, the API Approver is designed to keep the approval flow as automated as possible.

2. Build the rest of the policy:

   

   Configure the policy so it matches every transaction that should be evaluated by your API Approver. Depending on your use case, this may include all vaults, specific vault groups, particular transaction types, or other policy criteria.

   Important

   • The policy should be ranked above more specific rules so that every relevant transaction is evaluated before approval.
   • In the Initiator area: Make sure you do not select Any, so as not to include Validator Bot.
   • In the Origin area: Choose the group of vaults or vault groups you wish to monitor.
   • Fordefi's backend assumes that the transaction initiator always provides tacit approval, so it's very important that the API Approver API User is never used to initiate transactions. This is why the example does not use Any as the initiator in the policy.

3. Create transactions that match your policy and monitor your webhook server and policy matching. If all works as expected, any transaction that passes your validation rules will be approved automatically. Transactions that fail validation will be automatically aborted by the API Approver before they can proceed to cryptographic signing by the configured signer(s).