Documentation

Swapee has a simple REST API that can be used to register accounts and make payments and queries.

API Base URL

https://swapee.me/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.

export token=<your auth token>

POST /register

Register a new user account with a username and password

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

POST /login

Login to an account to get its auth token

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

POST /invoice

Create an invoice.

Request params
type
bitcoin or lightning
amount
amount in satoshis
webhook
(optional) endpoint to hit when the invoice is paid
secret
a secret for the webhook to check

Get a lightning invoice to receive funds

curl "https://swapee.me/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://swapee.me/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://swapee.me/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://swapee.me/api/invoice/bc1qmhfk9stzffhd9umzmld92vff7zg3mdlh7rvvaj" -H "content-type: application/json"'

POST /payments

Send a lightning payment

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

Send a bitcoin payment

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

Send an internal payment to another user

HASH=$(curl "https://swapee.me/api/invoice" -H "content-type: application/json" -H "Authorization: Bearer $token" -d '{ "invoice": { "amount": 1000, "type": "lightning" }, "user": { "username": "alice" } }' | jq -r '.hash'); curl "https://swapee.me/api/payments" -H "content-type: application/json" -H "Authorization: Bearer $token" -d '{ "amount": 5000, "hash": $HASH }'

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://swapee.me/api/payments" -H "content-type: application/json" -H "Authorization: Bearer $token"