Documentation

Coinos is free and open source software. The code is available at github.com/coinos

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 curl

API Base URL

https://staging.coinos.io/api

Auth Token

Sign in to view your auth token here, or get one from the /login endpoint. Save it in a variable called $token to run the examples. It gives full access to your account so keep it safe.

export token=<your auth token>

POST /register

curl "https://staging.coinos.io/api/register" -H "content-type: application/json" -d '{ "user": { "username": "demo", "password": "hunter2" } }'

POST /login

curl "https://staging.coinos.io/api/login" -H "content-type: application/json" -d '{ "username": "demo", "password": "hunter2" }'

GET /me

Get your account details and balance

curl "https://staging.coinos.io/api/me" -H "content-type: application/json"

POST /user

Update your account/settings

Request params (all optional)

username

string - letters and numbers, no spaces

display

string - spaces allowed

currency

string - three-letter ISO currency code e.g. CAD or USD

language

string - two-letter language code e.g. en, fr, es

curl "https://staging.coinos.io/api/user" -H "content-type: application/json" -d '{ "username": "demo", }'

POST /invoice

Create an invoice.

Request params

type (string, default: lightning)

bitcoin or lightning

fiat (boolean, default: false)

whether the amount is denominated in satoshis or local currency

amount (numeric)

amount to be paid

webhook (string, optional)

remote endpoint to call when the invoice is paid

secret (string, optional)

a secret value passed to the webhook to authenticate the request

Get a lightning invoice to receive funds

curl "https://staging.coinos.io/api/invoice" -H "content-type: application/json" -H "Authorization: Bearer $token" -d '{ "invoice": { "amount": 1000, "type": "lightning" } }'

Get a bitcoin address to receive funds

curl "https://staging.coinos.io/api/invoice" -H "content-type: application/json" -H "Authorization: Bearer $token" -d '{ "invoice": { "amount": 3141, "type": "bitcoin" } }'

Sample response

{ "amount":3141 "tip":0 "type":"bitcoin" "prompt":false "rate":31836.9702667 "hash":"bc1qmhfk9stzffhd9umzmld92vff7zg3mdlh7rvvaj" "text":"bitcoin:bc1qmhfk9stzffhd9umzmld92vff7zg3mdlh7rvvaj?amount=0.00003141" "currency":"CAD" "uid":"a9770421-3f65-11ed-9f57-0242ac2a0004" "received":0 "created":1677537428134 }

You can check the received field to see how much has been paid

Specify a webhook to be called when an invoice is paid

curl "https://staging.coinos.io/api/invoice" -H "content-type: application/json" -H "Authorization: Bearer $token" -d '{ "invoice": { "type": "lightning", "webhook": "https://example.com/payment/received", "secret": "webhooksecret" } }'

GET /invoice/:hash

Fetch an invoice by passing a bitcoin address or lightning payment hash

curl "https://staging.coinos.io/api/invoice/bc1qmhfk9stzffhd9umzmld92vff7zg3mdlh7rvvaj" -H "content-type: application/json"'

POST /payments

Send a lightning payment

curl "https://staging.coinos.io/api/payments" -H "content-type: application/json" -H "Authorization: Bearer $token" -d '{ "payreq": "lnbc1pj94d8fsp5n77k340ps4m9jn7kp8he8yynpddvurv6mcsrrqpnq5l2jxdxzlwqpp5m96pqhc5nrlk8cqsu9ufdxxa43sarp8vwf9egvm2pg9nl0zu9r8qdq2vdhkjmn0wvxqztgcqpjrzjqwhmav82kntsppmkp8jp4vg4h9nns78tsy8mg7ve4lq5txrkp0h56zlarvqqdtcqqsqqqqqqqqqqp6cq9q9qyysgqzxlypywzphyujm3ga5j5csfcmqvlnae0fgnvymkaaw94eeg7py5rqzysyjkr3ev2snq63qpsc69vf54adkd0szvmvwt5cuadjnuy95sq4xfa40" }'

Send an internal payment to another user

curl "https://staging.coinos.io/api/send" -H "content-type: application/json" -H "Authorization: Bearer $token" -d '{ "amount": 5000, "username": "alice" }'

POST /bitcoin/send

Send a bitcoin payment

curl "https://staging.coinos.io/api/bitcoin/send" -H "content-type: application/json" -H "Authorization: Bearer $token" -d '{ "amount": 5000, "address": "bc1q3unh97w4rmelflrm2hvdwz37d8kray3vn4d5ca" }'

GET /payments

Get all payments sent or received by the current user

Query params

start

only payments after this unix time

end

only payments before this unix time

limit

limit to this integer number of results

offset

start limiting from this integer offset

curl "https://staging.coinos.io/api/payments" -H "content-type: application/json" -H "Authorization: Bearer $token"