Skip to content
This repository was archived by the owner on Oct 11, 2024. It is now read-only.

Commit 0d0b60f

Browse files
mintcloudmintcloud
authored
Merge pull request #428 from JoaoCampos89/development
WIP: Add instant docs
2 parents 617b5e1 + 45261f7 commit 0d0b60f

File tree

1 file changed

+225
-0
lines changed

1 file changed

+225
-0
lines changed

‎mdx/guides/integrate-instant.mdx‎

Lines changed: 225 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,225 @@
1+
# Introduction
2+
3+
0x Instant is a product built by 0x community that offers a convenient way for people to get access to a wide variety of tokens and other crypto-assets in just a few clicks. Developers can integrate the free, open source library into their applications or websites in order to both offer seamless access to crypto-assets, as well as gain a new source of revenue, with just a few lines of code.
4+
5+
<Image
6+
src="https://s3.eu-west-2.amazonaws.com/0x-wiki-images/instant_screenshot.png"
7+
align="center"
8+
alt="0x Instant"
9+
width="350px"
10+
padding="20px"
11+
marginBottom="40px"
12+
/>
13+
14+
Check out a live example on [mainnet](https://dexkit-storage.nyc3.digitaloceanspaces.com/zrx/v4/index.html).
15+
16+
## Libraries
17+
18+
0x Instant has the library `0x Instant UI component` that users will see and is powered by 0x API. Check out the `0x API` documentation [here](https://0x.org/docs/api). Check out the Instant Github repo [here](https://github.com/0xProject/0x-instant)
19+
20+
21+
## Affiliate Fees
22+
23+
As an end host of 0x Instant, you can charge users a fee on all trades made through Instant with the `affiliateFee` option. Simply specify an ethereum address and feePercentage (up to 5%), and a percentage of each transaction will be deposited into the specified address (denominated in the bought tokens).
24+
25+
# UI Integration
26+
27+
The 0x Instant UI powered by 0x API are bundled together in a convenient JS package for you. You can either download and serve the package yourself, or use the CDN-hosted version from 0x community.
28+
29+
<CodeTabs tabs={['html']}>
30+
31+
```html
32+
<!DOCTYPE html>
33+
<html>
34+
<head>
35+
<meta charset="utf-8" />
36+
<script src="https://dexkit-storage.nyc3.digitaloceanspaces.com/zrx/v4/instant.js"></script>
37+
</head>
38+
<body>
39+
<script type="text/javascript">
40+
function renderZeroExInstant() {
41+
zeroExInstant.render(
42+
{},
43+
'body',
44+
);
45+
}
46+
</script>
47+
<button onClick="renderZeroExInstant()">Hello World</button>
48+
</body>
49+
</html>
50+
```
51+
52+
53+
## Options Configuration
54+
55+
0x Instant is highly customizable to fit individual developer needs. Below are the different options that can be passed into the `render()` function above
56+
57+
## Optional
58+
59+
| Option | Description |
60+
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
61+
| `provider` | An instance of an Ethereum [provider](#q-what-is-a-provider), but teams may optionally source liquidity themselves and pass in specific [SignedOrders](#faqs). If none is provided, 0x instant will try to grab the injected provider if one exists, otherwise it will suggest the user to install MetaMask |
62+
| `walletDisplayName` | A display string for the wallet you are connected to. Defaults to our best guess (i.e. MetaMask, Coinbase Wallet) but should be provided if a custom provider is supplied as an optional config. |
63+
| `defaultSelectedTokenIn` | Default Token used on input in, must be available on the Token List |
64+
| `defaultSelectedTokenOut` | Default Token used on input out, must be available on the Token List |
65+
| `defaultAmountTokenIn` | Pre-fill the amount of in tokens Defaults to 0.
66+
| `defaultAmountTokenOut` | Pre-fill the amount of out tokens Defaults to 0. |
67+
| `tokenList` | Token list url where to fetch the list of supported tokens |
68+
| `chainId` | Chain Id of Ethereum network to connect to. Defaults to 1 (mainnet). |
69+
| `affiliateInfo` | An object specifying what % Token fee on bought tokens should be added to orders and where the fee should be sent. Max feePercentage is .05 (See examples below) |
70+
| `shouldDisableAnalyticsTracking` | An option to turn on / off analytics used to make Instant a better experience. Defaults to false. |
71+
| `onSuccess` | a function handler that is called when the token purchase through 0x Instant is complete. The function handler requests one argument: the transaction hash. |
72+
| `onClose` | a function handler that is called when the Instant overlay is closed. The function handler does not request any argument |
73+
74+
# Examples
75+
76+
77+
## With token list
78+
79+
Check all others token lists on [List Repository](https://tokenlists.org/) or create one following the [specification](https://github.com/Uniswap/token-lists) and host it on Github
80+
81+
```typescript
82+
zeroExInstant.render(
83+
{
84+
tokenList: 'https://tokens.coingecko.com/uniswap/all.json',
85+
},
86+
'body',
87+
);
88+
```
89+
90+
## Providing your own provider
91+
92+
This will give you more control over what provider is passed in and where RPC calls are directed
93+
94+
```typescript
95+
zeroExInstant.render(
96+
{
97+
provider: window.ethereum,
98+
walletDisplayName: 'Trust Wallet',
99+
},
100+
'body',
101+
);
102+
```
103+
104+
## Providing a Default Token In
105+
106+
```typescript
107+
zeroExInstant.render(
108+
{
109+
defaultSelectedTokenIn: '0xe41d2489571d322189246dafa5ebde1f4699f498'
110+
},
111+
'body',
112+
);
113+
```
114+
115+
## Example of Swap Token In by Token out with defined amount
116+
117+
```typescript
118+
zeroExInstant.render(
119+
{
120+
defaultSelectedTokenIn: '0xe41d2489571d322189246dafa5ebde1f4699f498',
121+
defaultSelectedTokenOut: '0x1985365e9f78359a9b6ad760e32412f4a445e862',
122+
defaultAmountTokenIn: 10000000000,
123+
},
124+
'body',
125+
);
126+
```
127+
128+
## Providing your own callback handler
129+
130+
```typescript
131+
zeroExInstant.render(
132+
{
133+
onSuccess: txHash => {
134+
console.log('Success! Transaction hash is: ' + txHash);
135+
},
136+
},
137+
'body',
138+
);
139+
```
140+
141+
# Learn about affiliate fees
142+
143+
As an end host of 0x Instant, you can charge users a fee on all trades made through Instant with the `affiliateFee` option. Simply specify an ethereum address and feePercentage (up to 5%), and a percentage of each transaction will be deposited into the specified address (denominated in bought tokens). If no affiliate address is specified it defaults to zero address.
144+
145+
Example: 3% of transaction volume (in ETH) will be deposited into 0x50ff5828a216170cf224389f1c5b0301a5d0a230
146+
147+
```typescript
148+
zeroExInstant.render(
149+
{
150+
affiliateInfo: {
151+
feeRecipient: '0x50ff5828a216170cf224389f1c5b0301a5d0a230',
152+
feePercentage: 0.03,
153+
},
154+
},
155+
'body',
156+
);
157+
```
158+
159+
# Roadmap
160+
161+
- Integration of all chains that 0x API supports:
162+
163+
- [x] Ethereum
164+
- [ ] BSC
165+
- [ ] Polygon
166+
- [ ] Avalanche
167+
- [ ] Fantom
168+
- [ ] Celo
169+
170+
171+
# FAQs
172+
173+
## General
174+
175+
### Q: What is a provider?
176+
177+
Check out this [article](/docs/guides/web3-provider-explained) in the guides section for an explanation of web3 providers. A dApp developer typically grabs this object from window.ethereum or window.web3.currentProvider. For advanced usage of providers check out the [examples](/docs/guides/web3-provider-explained#web3-provider-examples) of how to create your own providers
178+
179+
### Q: Can I swap through 0x Instant ERC-20 tokens like WETH or DAI?
180+
181+
0x Instant supports any ERC20 <-> ERC20 swaps.
182+
183+
### Q: Which networks will Instant supports?
184+
185+
Instant supports at the moment only ETH network, support for networks for BSC, Polygon, Fantom, Celo and Avalanche are on Roadmap.
186+
187+
### Q: This project has a roadmap?
188+
189+
Check the roadmap [here](#roadmap)
190+
191+
192+
## Mobile
193+
194+
### Q: How can I make 0x Instant work in my mobile app?
195+
196+
For apps using React Native or apps that have a web view, the 0x API will work out of the box with your application. For apps that are written in a native language like Java or Swift, you will need to wrap the asset-swapper logic in a JS interpreter.
197+
198+
## Affiliates
199+
200+
### Q: How do I make money as an affiliate?
201+
202+
If you host 0x Instant, you can designate an address that you own to receive a small % of bought tokens that users spend on assets. The fee percent maxes out at 5%. You can configure this in the AffiliateInfo setting.
203+
204+
### Q: Do I need to set an affiliate?
205+
206+
Affiliate info is optional.
207+
208+
209+
## Support
210+
211+
### Q: How can I get help integrating Instant?
212+
213+
Create question on [StackExchange](https://ethereum.stackexchange.com/questions/tagged/0x)
214+
215+
### Q: Who maintains this package?
216+
217+
This package is maintained by community member @JoaoCampos89 under a grant gave by "the 0x community"
218+
219+
### Q: I found a bug on instant?
220+
221+
Please open issue on [Instant Github](https://github.com/0xProject/0x-instant/issues)
222+
223+
### Q: The token that I want to swap keeps failling?
224+
225+
Instant powered by 0x API supports any Token that has liquidity and follows ERC20 standard. Tokens that not follow ERC20 standard can fail as for instance deflationary or with buy back functions.

0 commit comments

Comments
 (0)