REST API

Fast, parsed REST endpoints for wallets, NFTs, tokens, and transactions. Compatible with Shyft's REST API — swap the URL and API key to use FalconQ.

Base URL

https://api.falconq.xyz/sol/v1

All endpoints use mainnet-beta as the default network. Pass ?network=devnet for devnet.

Authentication

Three methods — pick whichever fits your stack:

# 1. x-api-key header (Shyft-compatible — drop-in replacement)
curl -X GET "https://api.falconq.xyz/sol/v1/wallet/balance?network=mainnet-beta&wallet=11111111111111111111111111111111" \
  -H "x-api-key: fq_rpc_live_YOUR_KEY"

# 2. Authorization: Bearer (FalconQ standard)
curl -X GET "https://api.falconq.xyz/sol/v1/wallet/balance?network=mainnet-beta&wallet=11111111111111111111111111111111" \
  -H "Authorization: Bearer fq_rpc_live_YOUR_KEY"

# 3. Query parameter
curl -X GET "https://api.falconq.xyz/sol/v1/wallet/balance?network=mainnet-beta&wallet=11111111111111111111111111111111&api-key=fq_rpc_live_YOUR_KEY"

REST endpoints use your RPC key (fq_rpc_live_...) and are limited to 600 requests per minute per endpoint group.

Wallet APIs

Get Balance

Returns the SOL balance (in SOL, not lamports) for a given wallet address.

Parameters: network (mainnet-beta / devnet / testnet), wallet (base58 pubkey).

GET /sol/v1/wallet/balance?network=mainnet-beta&wallet=11111111111111111111111111111111

Response

{
  "success": true,
  "message": "Balance fetched successfully",
  "result": { "balance": 0.9908624 }
}

Get All Tokens

Returns every SPL token (and Token 2022) held by a wallet, with balances and metadata.

Parameters: network, wallet.

GET /sol/v1/wallet/all_tokens?network=mainnet-beta&wallet=9CWu3QcsvnK94RE2mtkzCy1EZp5YBmBhGETVG8GgiLMX

Token Balance

Returns the balance of a specific SPL token for a wallet.

Parameters: network, wallet, token (mint address).

GET /sol/v1/wallet/token_balance?network=mainnet-beta&wallet=9CWu3QcsvnK94RE2mtkzCy1EZp5YBmBhGETVG8GgiLMX&token=So11111111111111111111111111111111111111112

SNS Domains & Address Resolution

Get all .sol domains owned by a wallet, or resolve a domain to its pubkey.

# Get domains owned by a wallet
GET /sol/v1/wallet/get_domains?network=mainnet-beta&wallet=9CWu3QcsvnK94RE2mtkzCy1EZp5YBmBhGETVG8GgiLMX

# Resolve a wallet to its .sol name
GET /sol/v1/wallet/resolve_address?network=mainnet-beta&wallet=9CWu3QcsvnK94RE2mtkzCy1EZp5YBmBhGETVG8GgiLMX

Stake Accounts

Returns all stake accounts associated with a wallet, including delegation status and amounts.

Parameters: network, wallet_address, optional page and size (max 10).

GET /sol/v1/wallet/stake_accounts?network=mainnet-beta&wallet_address=9CWu3QcsvnK94RE2mtkzCy1EZp5YBmBhGETVG8GgiLMX

Collections

Groups all NFTs held by a wallet by their collection. Each collection includes the NFTs with full metadata.

GET /sol/v1/wallet/collections?network=mainnet-beta&wallet_address=9CWu3QcsvnK94RE2mtkzCy1EZp5YBmBhGETVG8GgiLMX

Additional Wallet Endpoints

POST	/sol/v1/wallet/send_sol	Build a send-SOL transaction (returns base64 encoded tx)
POST	/sol/v1/wallet/create_semi_wallet	Create a semi-custodial wallet with split-key model
GET	/sol/v1/wallet/decrypt_semi_wallet	Decrypt a semi-custodial wallet with password

NFT APIs

Read All NFTs (Paginated)

Returns all NFTs owned by a wallet with full metadata, paginated.

Parameters: network, address, optional page (default 1), size (default 50, max 50), update_authority (filter), refresh.

GET /sol/v2/nft/read_all?network=mainnet-beta&address=9CWu3QcsvnK94RE2mtkzCy1EZp5YBmBhGETVG8GgiLMX&page=1&size=50

Response

{
  "success": true,
  "message": "NFTS in your wallet",
  "result": {
    "nfts": [
      {
        "name": "Mad Lads #1234",
        "symbol": "MAD",
        "royalty": 5,
        "image_uri": "https://arweave.net/...",
        "metadata_uri": "https://arweave.net/...",
        "mint": "CCyTgSGBhMq3M6PJ..."
      }
    ],
    "total_count": 288,
    "page": 1,
    "size": 50,
    "total_pages": 6
  }
}

Read Single NFT

Returns full metadata for a single NFT by mint address.

GET /sol/v1/nft/read?network=mainnet-beta&token_address=CCyTgSGBhMq3M6PJ...

Read Selected

Batch-read up to 10 NFTs by their mint addresses.

POST /sol/v1/nft/read_selected
Content-Type: application/json

{
  "network": "mainnet-beta",
  "token_addresses": ["CCyTgSGBhMq3M6PJ...", "BkAHgUdSdGk..."
  ]
}

Search NFTs

Search NFTs in a wallet by creators, royalty range, attributes, or collection.

# Search by collection
GET /sol/v1/nft/search?network=mainnet-beta&wallet=9CWu3QcsvnK...&page=1&size=10

# Search with attribute filter
GET /sol/v1/nft/search?network=mainnet-beta&wallet=9CWu3QcsvnK...&attributes={"speed":{"gte":"50"}}

# Search with royalty range
GET /sol/v1/nft/search?network=mainnet-beta&wallet=9CWu3QcsvnK...&royalty={"gte":5,"lte":10}

Token API

Get Token Info

Returns metadata for any SPL token (or Token 2022) by mint address, including Token 2022 extensions.

GET /sol/v1/token/get_info?network=mainnet-beta&token_address=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v

Response (USDC)

{
  "success": true,
  "message": "Tokens info",
  "result": {
    "name": "USD Coin",
    "symbol": "USDC",
    "decimals": 6,
    "metadata_uri": "https://...",
    "image": "https://...",
    "address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "current_supply": 42817000000,
    "extensions": []
  }
}

Transaction APIs

Parse Transaction

Returns a human-readable parsed version of any transaction signature, with labeled actions, fee breakdown, and protocol info.

Parameters: network, txn_signature.

GET /sol/v1/transaction/parsed?network=mainnet-beta&txn_signature=5M2eFPgEkT6kF5VLXBBM7eF2CRJp8A4mGhfJLMcPVAwGec4hq3BpJtNkXL8WxUFfZB4qgvmFNbkSfbD7QMrPi2D4

Transaction History

Returns parsed transaction history for an address (last 3-4 days). Supports pagination with before/until signature cursors.

Parameters: network, account, optional tx_num (max 100), before_tx_signature, enable_raw (includes raw tx data).

GET /sol/v1/transaction/history?network=mainnet-beta&account=9CWu3QcsvnK94RE2mtkzCy1EZp5YBmBhGETVG8GgiLMX&tx_num=10

Parse Selected (Batch)

Batch-parse up to 100 transaction signatures in a single POST request.

POST /sol/v1/transaction/parse_selected
Content-Type: application/json

{
  "network": "mainnet-beta",
  "transaction_signatures": ["sig1...", "sig2..."]
}

Send Transaction

Submit a signed base64-encoded transaction to the Solana network.

POST /sol/v1/transaction/send_txn
Content-Type: application/json

{
  "network": "mainnet-beta",
  "encoded_transaction": "AQAAAA..."
}

Send Many Transactions

Batch-submit up to 100 signed transactions. Waits until all reach the specified commitment level.

POST /sol/v1/transaction/send_many_txns
Content-Type: application/json

{
  "network": "mainnet-beta",
  "encoded_transactions": ["AQAA...", "AQAB..."],
  "commitment": "confirmed"
}

Note: Transaction history is limited to the past 3-4 days. For historical data beyond this window, use the RPC getSignaturesForAddress and getTransaction methods.

Storage APIs

Upload to IPFS

Upload any file to IPFS via decentralized storage. Content-addressed — the same file always returns the same CID.

POST /sol/v1/storage/upload
Content-Type: multipart/form-data

# With curl:
curl -X POST "https://api.falconq.xyz/sol/v1/storage/upload" \
  -H "x-api-key: fq_rpc_live_YOUR_KEY" \
  -F "file=@nft-image.png"

Response

{
  "success": true,
  "message": "Metadata created successfully",
  "result": {
    "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "uri": "https://ipfs.io/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
  }
}

Create NFT Metadata

Create Metaplex-compliant NFT metadata JSON and upload it to IPFS in one call.

POST /sol/v1/metadata/create
Content-Type: application/json

{
  "name": "My NFT",
  "symbol": "MYNFT",
  "description": "An awesome NFT",
  "image": "https://ipfs.io/ipfs/bafy...image",
  "attributes": [
    { "trait_type": "Speed", "value": "100" }
  ],
  "creator": "BvzKvn6nUUAYtKu2pH3h5SbUkUNcRPQawg4bURBiojJx",
  "share": 100,
  "royalty": 5
}

Error Codes

HTTP Status	Code	Description
401	MISSING_KEY	No API key provided in headers or query params
403	INVALID_KEY	API key is invalid, inactive, or expired
403	UNAUTHORIZED_PRODUCT	Key is for a different product (e.g., gRPC key used on REST)
429	RATE_LIMITED	Rate limit exceeded — check the Retry-After header
503	UPSTREAM_UNAVAILABLE	Upstream Shyft service is temporarily unavailable

Shyft Compatibility

All FalconQ REST endpoints are fully compatible with Shyft's REST API. To migrate from Shyft, simply:

Replace https://api.shyft.to with https://api.falconq.xyz
Replace your Shyft API key with your FalconQ RPC key (fq_rpc_live_...)
Keep all endpoint paths, query parameters, and request bodies identical

For the complete Shyft API specification, see the Shyft API documentation.