blob: c323f9bd2242fb63fcf9880f8023cb2fa72317aa (
plain) (
blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
|
<script>
import { copyNoNewlines as copy } from "$lib/utils";
import { PUBLIC_DOMAIN, PUBLIC_COINOS_URL } from "$env/static/public";
import Code from "$comp/Code.svelte";
import Icon from "$comp/Icon.svelte";
let { data } = $props();
let { user, ro, token } = data;
let api = PUBLIC_DOMAIN.includes("localhost")
? `${PUBLIC_COINOS_URL}`
: `https://${PUBLIC_DOMAIN}/api`;
let tokenSample = token
? `export token="${token}"`
: `export token=<your auth token>`;
let roSample = `export token="${ro}"`;
</script>
{#snippet cp(something)}
<button type="button" class="ml-auto" onclick={() => copy(something)}>
<iconify-icon noobserver icon="ph:copy-bold" width="42"></iconify-icon>
</button>
{/snippet}
<div class="space-y-8 lg:text-xl mt-20 pt-20 md:pt-0 w-full max-w-full">
<h1 class="text-4xl">Documentation</h1>
<p class="text-secondary">
Coinos is free and open source software. The code is available at <a
href="https://github.com/coinos"
class="text-secondary underline">github.com/coinos</a
>
</p>
<p class="text-secondary">
Coinos has a REST API that can be used to register accounts and make
payments. The following examples show how you can call the API with <a
href="https://curl.se/"
class="text-secondary underline">curl</a
>
</p>
<h2 class="text-2xl">API Base URL</h2>
<div
class="bg-primary text-primary-content rounded-lg p-4 flex gap-4 items-center"
>
<div>{api}</div>
{@render cp(api)}
</div>
<h2 class="text-2xl">Auth Token</h2>
<p class="text-secondary">
{#if user && token}
This token authorizes you to use the API as <b>{user.username}</b>.
{:else}
<a href="/login" class="font-bold">Sign in</a> to view your auth token here,
or get one from the /login endpoint.
{/if}
Save it in a variable called <b>$token</b> to run the examples. It gives full access to your account so keep it safe.
</p>
<div
class="bg-primary text-primary-content rounded-lg p-4 flex gap-4 items-center"
>
<div class="w-full break-all">{tokenSample}</div>
{@render cp(tokenSample)}
</div>
{#if ro}
<p class="text-secondary">
This read-only token has permission to create invoices and fetch
payments but can't be used to make withdrawals
</p>
<div
class="bg-primary text-primary-content rounded-lg p-4 flex gap-4 items-center"
>
<div class="w-full break-all">{roSample}</div>
{@render cp(roSample)}
</div>
{/if}
<h2 class="text-2xl">POST /register</h2>
<p class="text-secondary">
Register a new user account with a username and password
</p>
<Code sample="register" />
<h2 class="text-2xl">POST /login</h2>
<p class="text-secondary">Login to an account to get its auth token</p>
<Code sample="login" />
<h2 class="text-2xl">GET /me</h2>
<p class="text-secondary">Get your account details and balance</p>
<Code sample="me" />
<h2 class="text-2xl">POST /user</h2>
<p class="text-secondary">Update your account/settings</p>
<div>Request params (all optional)</div>
<div class="grid grid-cols-3 ml-2">
<div class="font-bold">username</div>
<div class="col-span-2">string - letters and numbers, no spaces</div>
<div class="font-bold">display</div>
<div class="col-span-2">string - spaces allowed</div>
<div class="font-bold">currency</div>
<div class="col-span-2">
string - three-letter ISO currency code e.g. CAD or USD
</div>
<div class="font-bold">language</div>
<div class="col-span-2">
string - two-letter language code e.g. en, fr, es
</div>
</div>
<Code sample="update" />
<h2 class="text-2xl">POST /invoice</h2>
<p class="text-secondary">Create an invoice.</p>
<div class="text-secondary">
<div>Request params</div>
<div class="grid grid-cols-3 ml-2">
<div class="font-bold">type (string, default: lightning)</div>
<div class="col-span-2">bitcoin or lightning</div>
<div class="font-bold">fiat (boolean, default: false)</div>
<div class="col-span-2">
whether the amount is denominated in satoshis or local currency
</div>
<div class="font-bold">amount (numeric)</div>
<div class="col-span-2">amount to be paid</div>
<div class="font-bold">webhook (string, optional)</div>
<div class="col-span-2">
remote endpoint to call when the invoice is paid
</div>
<div class="font-bold">secret (string, optional)</div>
<div class="col-span-2">
a secret value passed to the webhook to authenticate the request
</div>
</div>
</div>
<p>Get a lightning invoice to receive funds</p>
<Code sample="lightningInvoice" />
<p>Get a bitcoin address to receive funds</p>
<Code sample="bitcoinAddress" />
<p>Sample response</p>
<Code sample="invoiceResponse" />
<p>You can check the <b>received</b> field to see how much has been paid</p>
<p>Specify a webhook to be called when an invoice is paid</p>
<Code sample="webhook" />
<h2 class="text-2xl">GET /invoice/:hash</h2>
<p class="text-secondary">
Fetch an invoice by passing a bitcoin address or lightning payment hash
</p>
<Code sample="fetchInvoice" />
<h2 class="text-2xl">POST /payments</h2>
<p class="text-secondary">Send a lightning payment</p>
<Code sample="lightning" />
<p class="text-secondary">Send an internal payment to another user</p>
<Code sample="internal" />
<h2 class="text-2xl">POST /bitcoin/send</h2>
<p class="text-secondary">Send a bitcoin payment</p>
<Code sample="bitcoin" />
<h2 class="text-2xl">GET /payments</h2>
<p class="text-secondary">
Get all payments sent or received by the current user
</p>
<div class="text-secondary">
<div>Query params</div>
<div class="grid grid-cols-3 ml-2">
<div class="font-bold">start</div>
<div class="col-span-2">only payments after this unix time</div>
<div class="font-bold">end</div>
<div class="col-span-2">only payments before this unix time</div>
<div class="font-bold">limit</div>
<div class="col-span-2">limit to this integer number of results</div>
<div class="font-bold">offset</div>
<div class="col-span-2">start limiting from this integer offset</div>
</div>
</div>
<Code sample="payments" />
</div>
|
