BlockWyre’s
Documentation
Everything you need to build on BlockWyre’s AI-driven financial infrastructure — from your first API call to production-grade custody, payments and off-ramp integrations.
REST
+ Webhooks
Ed25519
Signed requests
WebSocket
Live market prices
Sandbox
Its own host, dashboard and keys
Getting started with BlockWyre
This section walks you through the initial setup and the key requirements for using our API. Get sandbox access, upload your public key, sign a request, and you’re ready to go live.
Request sandbox access
There is no self-serve sign-up. Contact us: we create your sandbox workspace, and its first user gets an email invitation to set a password.
Contact us →Log in to the sandbox dashboard
Sign in at dashboard-sandbox.blockwyre.com with the password you set from the invitation.
dashboard-sandbox.blockwyre.com →Upload your Ed25519 public key
Generate a key pair on your server, then upload the public key in Admin Access › API Keys. The private key never leaves your server.
Create an API key →Sign your requests
Send every request with Authorization: APIKey <signed-jwt>, a short-lived JWT signed with your private key for that one request.
Go live
For production, create a key in the production dashboard, dashboard.blockwyre.com, and switch the base URL to api.blockwyre.com. Sandbox keys work only against the sandbox, production keys only against production.
# SIGNED_JWT: signed with your private key for exactly this method and URI# An account-scoped key lists its own account: drop ?account_id=…curl "https://api-sandbox.blockwyre.xyz/v3/balances?account_id=cst_0123456789abcdef0123456789" \ -H "Authorization: APIKey $SIGNED_JWT" # 200 OK{ "data": [ { "bank_account_id": "bnk_01k8x4m2qv7r3t5w9y1a3c5e7g", "bank_account_name": "Operating", "bank_account_is_default": true, "coin": "USD", "available": { "amount": "1250.75", "currency": "USD" }, "pending_credits": { "amount": "500.00", "currency": "USD" }, "pending_debits": { "amount": "100.25", "currency": "USD" }, "reserved": { "amount": "0", "currency": "USD" } } ], "totals": [ { "coin": "USD", "available": { "amount": "1250.75", "currency": "USD" }, "pending_credits": { "amount": "500.00", "currency": "USD" }, "pending_debits": { "amount": "100.25", "currency": "USD" }, "reserved": { "amount": "0", "currency": "USD" } } ]}Authentication
Every request, on /v3 and /api/v2 alike, carries one header: Authorization: APIKey <signed-jwt>. The JWT is signed with your Ed25519 private key for that one request; BlockWyre only ever holds your public key.
Keep your private_key.pem on your server: never in client code or source control. If it is ever exposed, delete that API key in the dashboard and create a new one from a new key pair. How to build and sign the JWT: Authentication.
Understand the response model
Three concepts cover almost everything you’ll deal with day to day.
Standard
Responses
What a successful answer looks like: a single resource comes back as the object itself, and a list puts its items in data with the paging fields beside them.
Learn moreCommon HTTP
Status Codes
A detailed overview of the HTTP status codes you might encounter, and exactly what each one signals about your request.
Learn moreError
Handling
On failure, the body carries the HTTP status in code, a snake_case message to branch on, and details when there is more to say.
Learn moreCommon HTTP status codes
A detailed overview of the codes you might encounter and what each one means.
| Code | Meaning | |
|---|---|---|
| 200 | OKThe request succeeded and the response body contains the result. | The request succeeded and the response body contains the result. |
| 201 | CreatedA new resource, such as a bank account or an ACH pull, was created. | A new resource, such as a bank account or an ACH pull, was created. |
| 400 | Bad RequestThe request was malformed or missing required parameters. | The request was malformed or missing required parameters. |
| 401 | UnauthorizedThe key, signature or JWT claims failed, or the key belongs to the other environment. | The key, signature or JWT claims failed, or the key belongs to the other environment. |
| 403 | ForbiddenAuthenticated but not allowed, such as an account-scoped key naming another account. | Authenticated but not allowed, such as an account-scoped key naming another account. |
| 404 | Not FoundThe resource does not exist, or is not visible to this key. | The resource does not exist, or is not visible to this key. |
| 429 | Too Many RequestsMore than 100 requests in a minute from your IP. Wait the seconds in Retry-After. | More than 100 requests in a minute from your IP. Wait the seconds in Retry-After. |
| 500 | Server ErrorSomething went wrong on our side. Retry with backoff; on a /v3 write, send the same Idempotency-Key. | Something went wrong on our side. Retry with backoff; on a /v3 write, send the same Idempotency-Key. |
Error handling
On /v3, an error answers with a JSON body: code repeats the HTTP status, message is a snake_case code to branch on, and details adds context when there is any.
# 404 Not Found{ "code": 404, "message": "bank_account_not_found"}BlockWyre’s Sandbox
A separate environment for building and testing your integration before you go live. Safely experiment with transaction flows, API integrations and other functionality, then switch the base URL and the key to production.
- The same API as production, on its own host
- Its own dashboard and keys: a sandbox key works only against the sandbox API
- KYC and KYB run through the verification provider, as in production; the outcome simulator behind verificationUrl belongs to the deprecated v2 flow
# Sandbox: log in and create keys at# https://dashboard-sandbox.blockwyre.comBLOCKWYRE_BASE_URL= \ "https://api-sandbox.blockwyre.xyz" # Production: keys from# https://dashboard.blockwyre.com# BLOCKWYRE_BASE_URL="https://api.blockwyre.com"Need more help?
Already a customer? Write to support and we’ll get you unblocked. New to BlockWyre? Contact us and we’ll set up your sandbox.