Skip to content

Commit fecc092

Browse files
paullinatorpaullinator
authored
Merge pull request #410 from EdgeApp/paul/apiReq
Add api requirements and template plugin
2 parents 25f86e0 + c6daadb commit fecc092

28 files changed

+4922
-1502
lines changed

‎.cursor/agents/review-api-requirements.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
name: review-api-requirements
3+
description: Reviews exchange plugins for compliance with provider API requirements. Use when reviewing swap or fiat plugin implementations.
4+
---
5+
6+
Review the branch/pull request for compliance with Edge exchange provider API requirements.
7+
8+
## Context Expected
9+
10+
You will receive:
11+
- Repository name (edge-exchange-plugins)
12+
- Branch name
13+
- List of changed files to review
14+
15+
## How to Review
16+
17+
1. Read the API requirements document: `docs/API_REQUIREMENTS.md`
18+
2. Read the changed plugin files provided in context
19+
3. For each requirement in the API doc, verify the plugin implementation meets it (where applicable)
20+
4. Report findings with specific file:line references
21+
22+
## Key Areas to Check
23+
24+
- Chain and token identification (using identifiers, not just ticker symbols)
25+
- Order ID extraction and status page URI
26+
- Error handling (all errors returned at once, processed in priority order)
27+
- Bi-directional quoting support (from, to, max)
28+
- Transaction status API integration
29+
- Account activation handling (XRP, HBAR, etc.)
30+
- Limit error amounts in correct denomination

‎.cursor/agents/review-chain-mapping.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
---
2+
name: review-chain-mapping
3+
description: Reviews exchange plugins for correct chain mapping implementation. Use when reviewing plugins that add or modify chain support.
4+
---
5+
6+
Review the branch/pull request for correct chain mapping implementation.
7+
8+
## Context Expected
9+
10+
You will receive:
11+
- Repository name (edge-exchange-plugins)
12+
- Branch name
13+
- List of changed files to review
14+
15+
## How to Review
16+
17+
1. Read the chain mapping documentation: `docs/CHAIN_MAPPING_SYNCHRONIZERS.md`
18+
2. Read the changed plugin and mapping files provided in context
19+
3. Verify the mapping implementation follows the documented patterns
20+
4. Report findings with specific file:line references
21+
22+
## Key Areas to Check
23+
24+
- Source mappings in `scripts/mappings/` (provider code → Edge plugin ID)
25+
- Generated runtime mappings in `src/mappings/` (Edge plugin ID → provider code)
26+
- Synchronizer implementation if adding a new provider
27+
- New chains mapped correctly (not left as `null` without reason)
28+
- EVM chains using `chainId` where applicable
29+
- Mapping file imported and used correctly in plugin code

‎.cursor/agents/review-edge-exchange-plugins.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
name: review-edge-exchange-plugins
3+
description: Orchestrator that launches exchange plugin review subagents. Use when reviewing exchange plugin implementations.
4+
---
5+
6+
Review the branch/pull request for compliance with Edge exchange plugin conventions.
7+
8+
## Context Expected
9+
10+
You will receive:
11+
- Repository name (edge-exchange-plugins)
12+
- Branch name
13+
- List of changed files to review
14+
15+
## Orchestration
16+
17+
Launch ALL FOUR sub-agents in parallel, passing them the full context you received:
18+
19+
1. **review-api-requirements** - Reviews for compliance with `docs/API_REQUIREMENTS.md`
20+
2. **review-chain-mapping** - Reviews chain mapping with `docs/CHAIN_MAPPING_SYNCHRONIZERS.md`
21+
3. **review-plugin-creation** - Reviews plugin structure with `docs/CREATING_AN_EXCHANGE_PLUGIN.md`
22+
4. **review-exchange-bugs** - Reviews for common bugs and poor patterns
23+
24+
## Output
25+
26+
Collect findings from all sub-agents and consolidate into a single report organized by category:
27+
28+
- **API Requirements Issues** - From review-api-requirements
29+
- **Chain Mapping Issues** - From review-chain-mapping
30+
- **Plugin Structure Issues** - From review-plugin-creation
31+
- **Bug Patterns** - From review-exchange-bugs
32+
33+
For each finding, include specific file:line references. Omit categories with no findings.

‎.cursor/agents/review-exchange-bugs.md‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
---
2+
name: review-exchange-bugs
3+
description: Reviews exchange plugins for common bugs and poor patterns. Use when reviewing any exchange plugin changes.
4+
---
5+
6+
Review the branch/pull request for common bugs and poor patterns specific to Edge exchange plugins.
7+
8+
## Context Expected
9+
10+
You will receive:
11+
- Repository name (edge-exchange-plugins)
12+
- Branch name
13+
- List of changed files to review
14+
15+
## How to Review
16+
17+
1. Read the changed plugin files provided in context
18+
2. Check for each bug pattern listed below
19+
3. Report findings with specific file:line references
20+
21+
---
22+
23+
## Separate Handlers for Different Asset Types
24+
25+
When adding support for a new asset type (like Zcash), create a separate handler block rather than extending existing UTXO logic:
26+
27+
```typescript
28+
// Incorrect - mixing ZEC with general UTXO handling
29+
} else {
30+
// UTXO block
31+
if (fromWallet.currencyInfo.pluginId === 'zcash') {
32+
// ZEC-specific code mixed in
33+
}
34+
// ... rest of UTXO handling
35+
}
36+
37+
// Correct - separate block for ZEC
38+
} else if (fromWallet.currencyInfo.pluginId === 'zcash') {
39+
// ZEC-specific handling with all necessary checks
40+
if (thorAddress == null) throw new SwapCurrencyError(...)
41+
if (fromTokenId != null) throw new SwapCurrencyError(...)
42+
// ... ZEC-specific logic
43+
} else {
44+
// General UTXO handling
45+
}
46+
```
47+
48+
While Zcash is UTXO-based under the hood, Edge treats it differently. Keeping handlers separate makes code easier to maintain and reduces the chance of missing required checks.
49+
50+
---
51+
52+
## Include All Validation Checks in New Handlers
53+
54+
When creating a new asset handler by copying from an existing one, copy ALL validation checks:
55+
56+
```typescript
57+
// UTXO block has token rejection check
58+
} else {
59+
if (fromTokenId != null) {
60+
throw new SwapCurrencyError(swapInfo, request)
61+
}
62+
// ... rest of UTXO logic
63+
}
64+
65+
// New ZEC block - MUST include the same check
66+
} else if (fromWallet.currencyInfo.pluginId === 'zcash') {
67+
if (fromTokenId != null) {
68+
throw new SwapCurrencyError(swapInfo, request) // Don't forget this!
69+
}
70+
// ... ZEC logic
71+
}
72+
```
73+
74+
Missing validation checks can allow unsupported swap types to proceed.
75+
76+
---
77+
78+
## Remove Invalid Destination When Adding Support
79+
80+
If a previous commit blocked swaps to an asset, remove that block when adding destination support:
81+
82+
```typescript
83+
// Previous state: ZEC swaps blocked
84+
INVALID_CURRENCY_CODES.to.zcash = ['ZEC']
85+
86+
// Adding ZEC receive support but forgetting to remove the block:
87+
// New ZEC receive handler (lines 388-392) NEVER RUNS because
88+
// checkInvalidCodes throws SwapCurrencyError first (lines 129-135)
89+
90+
// Correct: Remove the invalid code entry when adding support
91+
// Delete: INVALID_CURRENCY_CODES.to.zcash = ['ZEC']
92+
```
93+
94+
Always trace the swap flow to ensure new handlers are actually reachable.

‎.cursor/agents/review-plugin-creation.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
name: review-plugin-creation
3+
description: Reviews exchange plugins for correct structure and conventions. Use when reviewing new plugins or significant plugin modifications.
4+
---
5+
6+
Review the branch/pull request for correct plugin structure and conventions.
7+
8+
## Context Expected
9+
10+
You will receive:
11+
- Repository name (edge-exchange-plugins)
12+
- Branch name
13+
- List of changed files to review
14+
15+
## How to Review
16+
17+
1. Read the plugin creation guide: `docs/CREATING_AN_EXCHANGE_PLUGIN.md`
18+
2. Read the changed plugin files provided in context
19+
3. Verify the plugin follows the documented structure and conventions
20+
4. Report findings with specific file:line references
21+
22+
## Key Areas to Check
23+
24+
- Plugin metadata (`swapInfo` with correct fields)
25+
- Init options with cleaners
26+
- Quote fetching (address retrieval, quote directions, error mapping)
27+
- Amount conversions using `denominationToNative`/`nativeToDenomination`
28+
- Transaction info (`EdgeSpendInfo` or `MakeTxParams`)
29+
- API response validation with cleaners
30+
- Plugin registration in `src/index.ts`
31+
- Correct plugin location (`src/swap/central/` vs `src/swap/defi/`)

‎docs/API_REQUIREMENTS.md‎

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
# Edge Exchange Provider API Requirements
2+
3+
This document defines the **technical API requirements** for third-party exchange providers seeking to integrate with the Edge wallet platform. It establishes standards for both **crypto-to-crypto swap providers** and **fiat on/off ramp providers**.
4+
5+
Key requirements include:
6+
1. [**Asset identification**](#1-chain-and-token-identification) using chain network identifiers and token contract addresses (not just ticker symbols)
7+
2. [**Order tracking**](#2-order-identification-and-status-page) via unique order IDs with unauthenticated status pages
8+
3. [**Structured error handling**](#3-error-handling) that returns all applicable errors (region restrictions, limits, unsupported assets) in a single response
9+
4. [**Bi-directional quoting**](#4-quoting-requirements) allowing users to specify either source or destination amounts
10+
5. [**Transaction status API**](#5-transaction-status-api) for querying order status
11+
6. [**Reporting APIs**](#6-reporting-api) for affiliate revenue tracking
12+
7. [**Account activation**](#7-account-activation) for assets like XRP and HBAR
13+
8. [**Affiliate revenue withdrawal**](#8-affiliate-revenue-withdrawal) with automated monthly payouts
14+
15+
For fiat on/off ramp providers specifically, the document adds requirements around:
16+
17+
9. [**User authentication**](#9-user-authentication) using cryptographic auth keys
18+
10. [**Regional and fiat currency support**](#10-regional-and-fiat-currency-support) with proper error handling
19+
11. [**KYC information**](#11-kyc-information) submission via API (not widget)
20+
12. [**Bank information**](#12-bank-information) submission for wire/SEPA transfers
21+
13. [**Verification**](#13-verification) code handling for phone and email
22+
14. [**Widget return URIs**](#14-widgets) for seamless app integration
23+
15. [**Off-ramp flow**](#15-off-ramp-flow) supporting no-widget transactions
24+
25+
## Requirements for both Swap and On/Off Ramp providers
26+
27+
### 1. Chain and Token Identification
28+
29+
API must allow requesting quotes and orders using a unique chain identifier and token identifier such as the contract address. This is to prevent confusion on which token is being referenced as well as to prevent the need to map provider tickers to tokens supported by Edge. Note that it is NOT sufficient to provide a separate endpoint to list all assets as this would require too many API calls to get a quote. This example shows how assets should be specified for a quote. The Edge exchange plugins will map the provider's chain network identifiers to edge specific chain network identifiers so they need not match exactly.
30+
31+
```json
32+
{
33+
"chainNetwork": "solana",
34+
"tokenId": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" // USDC
35+
}
36+
```
37+
38+
For EVM chains, API must allow requesting quotes using the universally accepted EVM `chainId` to specify the chain in addition to the token identifier. This allows automatic support of new EVMs with no need to add a mapping of provider chain identifiers to Edge chain identifiers. I.e.
39+
40+
```json
41+
{
42+
"chainNetwork": "evmGeneric",
43+
"chainId": 56 // BNB Smart Chain
44+
}
45+
```
46+
47+
### 2. Order Identification and Status Page
48+
49+
- Order requests must provide a unique `orderId` identifier that can be used to query status of the order via an unauthenticated API as well as connect the order with completed swaps reported via a reporting API.
50+
- Provider must provide an un-authenticated status page that uses the `orderId` to provide status on the swap. I.e. [`https://status.provider.com/orderStatus/{orderId}`](https://status.provider.com/orderStatus/{orderId)
51+
52+
### 3. Error Handling
53+
54+
Quote request errors must return all the following possible errors at once with all the mentioned details. This is to ensure that Edge can surface the most relevant error to the user. This prevents irrelevant errors like below limit errors from being surfaced to the user when the user would also be region restricted.
55+
56+
- Region restricted error
57+
- Asset unsupported error
58+
- Above or below limit errors with min/max amounts specified in both the source and destination asset
59+
60+
Limit errors need to be specified with a hardened error code and not using an arbitrary string. I.e. for swap from BTC to USDT
61+
62+
```json
63+
{
64+
"errors": [
65+
{
66+
"error": "OverLimitError",
67+
"sourceAmountLimit": 9.789, // BTC
68+
"destinationAmountLimit": 1000000 // USDT
69+
},
70+
{
71+
"error": "RegionRestricted"
72+
}
73+
]
74+
}
75+
```
76+
77+
### 4. Quoting Requirements
78+
79+
- Provider must allow bi-directional quoting such that the user can specify either the source asset amount or destination asset amount.
80+
81+
### 5. Transaction Status API
82+
83+
Provider must provide a transaction status API that allows querying of transaction status by `orderId`. This allows the Edge UI to show an updated transaction status to the user when they view the outgoing transaction.
84+
85+
```
86+
GET /api/status/{orderId}
87+
```
88+
89+
**Response:**
90+
91+
```json
92+
{
93+
"orderId": "{orderId}",
94+
"status": "pending" | "processing" | "infoNeeded" | "expired" | "refunded" | "completed"
95+
}
96+
```
97+
98+
### 6. Reporting API
99+
100+
Provider must provide an authenticated reporting API that allows querying of all transactions created using Edge. The reporting API must provide at minimum the following information for each transaction. Actual values are only examples. Similar values that can be mapped to the below are sufficient. API must allow paginated queries with start date, end date, and number of transactions.
101+
102+
```json
103+
{
104+
"orderId": "pr39dhg2409ryhgei39r", // Must match the orderId from quoting API
105+
"status": "pending" | "processing" | "infoNeeded" | "expired" | "refunded" | "completed",
106+
"createdDate": "2025-07-10T17:24:25.997Z",
107+
"completedDate": "2025-07-10T17:28:00.997Z",
108+
"sourceNetwork": "solana",
109+
"sourceTokenId": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
110+
"sourceCurrencyCode": "USDC",
111+
"sourceAmount": 118123,
112+
"sourceEvmChainId": null, // source not an EVM chain
113+
"destinationNetwork": "bitcoin",
114+
"destinationTokenId": null, // signified no token but primary gas token asset BTC
115+
"destinationCurrencyCode": "BTC",
116+
"destinationAmount": 1.01,
117+
"destinationEvmChainId": null, // destination not an EVM chain
118+
"payinAddress": "B8kGR7GpPh7GUsTgDgzjQYoJEFbpPr6q2V4iLEDeF6AD",
119+
"payoutAddress": "bc1q05wqn9nffg874fc6mp23lagfutawtwljx8udwy",
120+
"payinTxid": "wtpqAqCJj2iNte6iA6UUPtc5xgaRNGdjFuPk9B9VYFxkqxtSkSiC99gPU8MnGCEstbRTX3gQY5ErQn1475iuhFD",
121+
"payoutTxid": "2f6fbb24058e578d0a51842dfd8e79935df1702130c0a7ba3e8ef442bfc0f41c"
122+
}
123+
```
124+
125+
### 7. Account Activation
126+
127+
When a user requests an exchange into assets like XRP and HBAR, the provider should detect that the withdrawal address is not activated and send an activation transaction as part of the withdrawal.
128+
129+
### 8. Affiliate Revenue Withdrawal
130+
131+
Providers must automatically withdraw affiliate revenue funds in a single asset no later than 24 hours after the month close GMT time. Funds withdrawal should be allowed in at least BTC, ETH, and USDC to a fixed address verified by Edge. Edge should not be required to initiate withdrawal via an API or dashboard. Any changes to the withdrawal address should be verified with additional authentication such as 2FA codes and/or email verification.
132+
133+
## Additional requirements for fiat on/off ramp providers
134+
135+
### 9. User Authentication
136+
137+
Provider API should allow the Edge application to authenticate a user via cryptographically random authKey. The authKey should be created by Edge and passed into any quoting or order execution endpoint. If the authKey does not exist on the Provider system, the Provider's API should allow for account creation by receiving KYC info (if necessary) via API.
138+
139+
### 10. Regional and Fiat Currency Support
140+
141+
Provider quoting API should allow specifying not just the crypto asset but also the region (country/province) and fiat currency to receive a quote. Proper errors should be returned for unsupported regions and unsupported fiat currencies.
142+
143+
### 11. KYC Information
144+
145+
Provider API should allow the Edge application to provide basic KYC information and verification via API (not widget). Basic KYC information includes
146+
147+
- Name
148+
- Address
149+
- Phone number
150+
- Email address
151+
152+
### 12. Bank Information
153+
154+
For basic bank transfers (i.e. wire, SEPA) and any payment methods that do not have opposing regulatory requirements, Provider must have an API that allows Edge to submit bank information. I.e. account number, IBAN, and routing number.
155+
156+
### 13. Verification
157+
158+
- API should allow the Edge application to send KYC verification codes for phone and email verification. Verification codes are still generated by the provider servers, not Edge. Users enter verification codes into the Edge UI and are sent to provider via API.
159+
- An API should let Edge know when a specific piece of KYC information is missing or out of date to allow the Edge application to collect such info to send to the Provider's API.
160+
161+
### 14. Widgets
162+
163+
Any required widgets (ie for submitting credit card info or facial scan) must allow Edge to specify return URIs once the widget is complete. This allows Edge to close any webviews and continue with the application flow.
164+
165+
### 15. Off-Ramp Flow
166+
167+
For off-ramp transactions that have already had a payment method linked to the user's account, the provider must allow for a full "no-widget" flow by simply providing a crypto address that must receive funds and an expiration time (if necessary).

0 commit comments

Comments
 (0)