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

Commit 61196d0

Browse files
JoaoCampos89JoaoCampos89
committed
add instant docs
1 parent 617b5e1 commit 61196d0

File tree

1 file changed

+208
-0
lines changed

1 file changed

+208
-0
lines changed

‎mdx/guides/integrate-instant.mdx‎

Lines changed: 208 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,208 @@
1+
# Introduction
2+
3+
0x Instant is a product from the 0x core team 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).
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.
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 % ETH fee 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).
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+
184+
## Mobile
185+
186+
### Q: How can I make 0x Instant work in my mobile app?
187+
188+
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.
189+
190+
## Affiliates
191+
192+
### Q: How do I make money as an affiliate?
193+
194+
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.
195+
196+
## Support
197+
198+
### Q: How can I get help integrating Instant?
199+
200+
Create question on [StackExchange](https://ethereum.stackexchange.com/questions/tagged/0x)
201+
202+
### Q: Who maintains this package?
203+
204+
This package is maintained by community member @JoaoCampos89 under a grant gave by ZRX.
205+
206+
### Q: I found a bug on instant?
207+
208+
Please open issue on [Instant Github](https://github.com/0xProject/0x-instant/issues)

0 commit comments

Comments
 (0)