12 |
13 |
API overview
14 |
15 |
16 | Crypticle exposes a WebSocket API for reading and manipulating resources within the service and also for listening for realtime changes.
17 | The API adheres to the SocketCluster protocol.
18 | The following examples make use of the Asyngular JavaScript client.
19 |
20 |
21 | For more details about the API including the realtime CRUD API, visit crypticle.io.
22 |
23 |
24 |
25 |
26 |
Account RPCs
27 |
Signup
28 |
29 | try {
30 | let {accountId} = await socket.invoke('signup', {
31 | accountId: 'alice123',
32 | password: 'password123',
33 | admin: false,
34 | secretSignupKey: 'f502b122-5d7a-48cc-a0df-82d2a82465bd'
35 | });
36 | } catch (error) {
37 | // Handle failure
38 | }
39 |
40 |
41 | accountId is the account id.password is the account password.admin is a boolean which indicates whether or not the account should have admin privileges.-
45 |
46 | secretSignupKey is a secret key which needs to be provided if either:
47 |
48 |
49 | -
50 | The account being created is an admin account.
51 |
52 | -
53 | The server side
alwaysRequireSecretSignupKey config is true.
54 |
55 |
56 |
57 | If required, this key needs to match secretSignupKey from the service config file.
58 |
59 |
60 |
61 |
62 | Returns a Promise which will resolve with an object containing the accountId or which will be rejected if the signup operation fails on the server.
63 |
64 |
65 |
66 |
67 |
Login
68 |
69 | try {
70 | let {accountId} = await socket.invoke('login', {
71 | accountId: 'alice123',
72 | password: 'password123'
73 | });
74 | } catch (error) {
75 | // Handle login failure.
76 | }
77 |
78 |
79 | accountId is the account id.password is the account password.
82 |
83 | Returns a Promise which will resolve with an object containing the accountId or which will be rejected if the login operation fails on the server.
84 |
85 |
86 |
87 |
88 |
Transfer
89 |
90 | let {creditId, debitId} = await socket.invoke('transfer', {
91 | amount: '1000000000',
92 | toAccountId: 'alice123',
93 | data: 'Notes...'
94 | });
95 |
96 |
97 | amount is the amount of funds to send to the specified Crypticle account - It is expressed in the smallest possible cryptocurrency unit.toAccountId is the ID of the Crypticle account to send the funds to.data is an optional custom string to add to both the debit and credit transactions which will be created as a result of the transfer.debitId is an optional ID (string in UUID format) to use for the underlying debit transaction. If not provided, it will be automatically generated on the backend.creditId is an optional ID (string in UUID format) to use for the underlying credit transaction. If not provided, it will be automatically generated on the backend.
103 |
Returns a Promise which will resolve with an object containing the creditId and debitId (transaction IDs) of the underlying transactions.
104 |
105 |
106 |
107 |
Debit
108 |
109 | let {debitId} = await socket.invoke('debit', {
110 | amount: '1000000000',
111 | data: 'Notes...'
112 | });
113 |
114 |
115 | amount is the amount of funds to debit from the current authenticated account - It is expressed in the smallest possible cryptocurrency unit.data is an optional custom string to add to the debit transaction.debitId is an optional ID (string in UUID format) to use for the underlying debit transaction. If not provided, it will be automatically generated on the backend.
119 |
Returns a Promise which will resolve with an object containing the debitId (transaction ID) of the underlying transaction.
120 |
121 |
122 |
123 |
Get balance
124 |
125 | let balance = await socket.invoke('getBalance');
126 |
127 |
128 | Returns a Promise which will resolve with the current logged in user's account balance as a string.
129 |
130 |
131 |
132 |
133 |
Withdraw
134 |
135 | let {withdrawalId} = await socket.invoke('withdraw', {
136 | amount: '1100000000',
137 | toWalletAddress: '6942317426094516776R'
138 | });
139 |
140 |
141 | amount is the amount of funds to withdraw from your Crypticle account - It is expressed in the smallest possible cryptocurrency unit.toWalletAddress is the blockchain wallet address to send the funds to.
144 |
Returns a Promise which will resolve with an object containing the withdrawalId as a string.
145 |
146 |
147 |
148 |
Deposit
149 |
150 | To make a deposit, send a blockchain transaction to the deposit address of your Crypticle account (as shown on your console dashboard). The deposit wallet address for your account is shown on your console dashboard.
151 |
152 |
153 |
154 |
155 |
156 |
157 |
Admin RPCs
158 |
159 |
Impersonate
160 |
161 | try {
162 | let {accountId} = await socket.invoke('adminImpersonate', {
163 | accountId: 'alice123'
164 | });
165 | } catch (error) {
166 | // Handle impersonation failure.
167 | }
168 |
169 |
170 | accountId is the id of the account to impersonate.
172 |
173 | The Promise will resolve with an object containing the accountId or which will be rejected if the impersonate operation fails on the server.
174 |
175 |
176 |
177 |
178 |
Transfer
179 |
180 | let {creditId, debitId} = await socket.invoke('adminTransfer', {
181 | amount: '20000000',
182 | fromAccountId: 'bob456',
183 | toAccountId: 'alice123',
184 | data: 'Notes...'
185 | });
186 |
187 |
188 | amount is the amount of funds to send to the specified Crypticle account - It is expressed in the smallest possible cryptocurrency unit.fromAccountId is the ID of the Crypticle account from which to take the funds.toAccountId is the ID of the Crypticle account to send the funds to.data is an optional custom string to add to both the debit and credit transactions which will be created as a result of the transfer.debitId is an optional ID (string in UUID format) to use for the underlying debit transaction. If not provided, it will be automatically generated on the backend.creditId is an optional ID (string in UUID format) to use for the underlying credit transaction. If not provided, it will be automatically generated on the backend.
195 |
Returns a Promise which will resolve with an object containing the creditId and debitId (transaction IDs) of the underlying transactions.
196 |
197 |
198 |
199 |
Debit
200 |
201 | let {debitId} = await socket.invoke('adminDebit', {
202 | amount: '1000000000',
203 | fromAccountId: 'bob456',
204 | data: 'Notes...'
205 | });
206 |
207 |
208 | amount is the amount of funds to debit from the specified account - It is expressed in the smallest possible cryptocurrency unit.fromAccountId is the ID of the Crypticle account from which to debit the funds.data is an optional custom string to add to the debit transaction.debitId is an optional ID (string in UUID format) to use for the underlying debit transaction. If not provided, it will be automatically generated on the backend.
213 |
Returns a Promise which will resolve with an object containing the debitId (transaction ID) of the underlying transaction.
214 |
215 |
216 |
217 |
Credit
218 |
219 | let {creditId} = await socket.invoke('adminCredit', {
220 | amount: '1000000000',
221 | toAccountId: 'alice123',
222 | data: 'Notes...'
223 | });
224 |
225 |
226 | amount is the amount of funds to credit to the specified account - It is expressed in the smallest possible cryptocurrency unit.toAccountId is the ID of the Crypticle account to credit the funds to.data is an optional custom string to add to the credit transaction.creditId is an optional ID (string in UUID format) to use for the underlying credit transaction. If not provided, it will be automatically generated on the backend.
231 |
Returns a Promise which will resolve with an object containing the creditId (transaction ID) of the underlying transaction.
232 |
233 |
234 |
235 |
Get balance
236 |
237 | let balance = await socket.invoke('adminGetBalance', {
238 | accountId: 'bob456'
239 | });
240 |
241 |
242 | accountId is the ID of the Crypticle account to get the balance from.
244 |
245 | Returns a Promise which will resolve with the current balance of the specified account as a string.
246 |
247 |
248 |
249 |
250 |
Withdraw
251 |
252 | let {withdrawalId} = await socket.invoke('adminWithdraw', {
253 | amount: '234000000',
254 | fromAccountId: 'bob456',
255 | toWalletAddress: '6942317426094516776R'
256 | });
257 |
258 |
259 | amount is the amount of funds to withdraw from the specified Crypticle account - It is expressed in the smallest possible cryptocurrency unit.fromAccountId is the ID of the Crypticle account from which to withdraw the funds.toWalletAddress is the blockchain wallet address to send the funds to.
263 |
Returns a Promise which will resolve with an object containing the withdrawalId as a string.
264 |
265 |
266 |
267 |
268 |
269 |
Realtime CRUD channels
270 |
271 |
272 | Modifying data within Crypticle will cause change notifications to be published to specific channels.
273 | A channel can either represent a field of a specific resource or an entire view (collection).
274 |
275 |
276 |
277 |
278 |
Resource field changes
279 |
280 | You can subscribe to and consume realtime changes from a resource field channel like this:
281 |
282 |
283 |
284 | // This example shows how to detect when the 'settled' property of the
285 | // transaction with ID 1336b876-fda0-42dc-8834-b407d4d9d5fc has changed.
286 |
287 | let transactionSettledChannel = socket.subscribe(
288 | 'crud>Transaction/1336b876-fda0-42dc-8834-b407d4d9d5fc/settled'
289 | );
290 |
291 | (async () => {
292 | for await (let {value} of transactionSettledChannel) {
293 | // value will be true when the transaction has settled.
294 | }
295 | })();
296 |
297 |
298 | Note that it's possible to subscribe to a channel for any resource field defined in schema-data.js provided that the current authenticated user has the required access rights.
299 |
300 |
301 |
302 |
303 |
View changes
304 |
305 | You can subscribe to and consume realtime change notifications from a view channel like this:
306 |
307 |
308 |
309 | // This example shows how to detect when a transaction has been added to the
310 | // 'lastSettledTransactions' view for our account with ID 'bob456'.
311 |
312 | let lastSettledTransactionsChannel = socket.subscribe(
313 | 'crud>lastSettledTransactions({"accountId":"bob456"}):Transaction'
314 | );
315 |
316 | (async () => {
317 | for await (let data of lastSettledTransactionsChannel) {
318 | // This loop will iterate once when whenever the view has been
319 | // modified (e.g. a new transaction was added).
320 | // It's a good time to re-fetch our latest account balance.
321 | let balance = await socket.invoke('getBalance');
322 | }
323 | })();
324 |
325 |
326 | Note that it's possible to subscribe to a channel for any view defined in schema-data.js provided that the current authenticated user has the required access rights.
327 |
328 |
329 |