Build on the Arxium devnet

Endpoints and API keys

The devnet is reached through one gateway with one key. The chain id is corechain-devnet.

Get an API key

Sign in at retracer.arxium.network with GitHub and create a key for corechain-devnet. The key starts with rk_ and is shown only once, so copy it when it appears. Send it as Authorization: Bearer rk_…. The same key works for the node RPC and the indexer.

• Free keys allow 10 requests per second and one open event stream.
• Over the limit you get 429 with Retry-After and X-RateLimit-* headers. Wait the number of seconds in Retry-After, which is at most 10, then retry.
• Send a User-Agent that names your app. Some library defaults (Python's urllib, for one) are blocked at the edge with error code: 1010 before your key is ever checked.
• The indexer is read-only. Writes, meaning signed actions, go to the node RPC.

Quickstart

You need Node 20 or later. The arx CLI comes with the TypeScript SDK, which has no runtime dependencies and also runs in browsers and Workers.

1. Install and connect

npm install -g @arxium-protocol/sdk
arx --version

export ARX_RPC=https://retracer-api.arxium.network/rpc/corechain-devnet
export ARX_TOKEN=rk_...            # your API key
arx query status

status prints the chain name, tip height and genesis_hash. Keep the genesis hash: it identifies this chain, and you'll compare against it in the verification section below.

2. Get a key and test ARX

Sign in at console.arxium.network. Generate a signing key under Settings. It's created and encrypted in your browser, and the passphrase never leaves it. Then open Faucet and claim 10 ARX. You can claim again every 100 blocks, and the faucet only pays the Console key. Back in Settings, click Export encrypted key and bring the file into the CLI:

arx keys import --file arxium-devnet-key-xxxxxxxx.json
export ARX_KEY=arxium-devnet-key-xxxxxxxx.json
arx keys show                       # address, no passphrase needed
arx query account arx1...           # balance 10000000000 = 10 ARX

Amounts are integers in base units: 1 ARX = 1,000,000,000 IUM. arx asks for the passphrase when it signs, or reads it from ARX_PASSPHRASE in scripts. arx keys new makes a key entirely offline, but it starts at zero balance.

3. Send your first transfer

Make a second key and send it 1 ARX. You'll use it as the asset holder later.

arx keys new holder.json            # prints the holder's address
arx send transfer arx1holder... 1000000000

send fetches your nonce, signs locally, submits, and waits for the block. The output has the signed action, including its signature, and "status": "confirmed" with the height. A rejected action prints the node's reason and exits 1. Each action costs a flat fee of 0.001 ARX.

4. See it in the Explorer

Open explorer.arxium.network/address/arx1… with either address, or paste the signature into the Explorer's search. The transfer is listed with its block and finality.

5. Verify it yourself

arx verify <signature>
{
  "signature": "2523…b904",
  "finalized": true,
  "signatureValid": true,
  "height": 22
}

arx verify doesn't take the node's word for anything except where the action landed. It fetches that block and checks that it's finalized and contains your action. Then it verifies the Ed25519 signature against the sender's address on your own machine.

Issue a regulated asset

This walkthrough covers what Arxium is for. You register an asset that only KYC'd holders in Switzerland or Liechtenstein may hold. Transfers to the holder are refused until a registered attestor grants the right claims. The chain enforces the rules on every transfer, so no app can skip them.

Two roles are involved. The issuer registers the asset and sets its rules. An attestor, normally a KYC provider, vouches for accounts. In production they're different companies. On devnet you play both, using the Console key from the quickstart.

0. Ask for the attestor role

Only accounts on the chain's attestor registry can grant attestations, and on devnet the Arxium team maintains that registry. Email your Console key's address to contact@arxium.network with the subject Devnet attestor. Once it's registered, your address appears in curl -H "Authorization: Bearer $ARX_TOKEN" $ARX_RPC/attestors. You can do steps 1 and 2 while you wait.

1. Register the asset

ISSUER=arx1...      # your Console key (ARX_KEY)
HOLDER=arx1...      # holder.json from the quickstart

# <asset-id> <symbol> <name> <decimals> [required claims] [allowed jurisdictions]
arx send register-asset fund-a FUNDA "Fund A" 0 kyc CH,LI

ASSET=$(curl -s -H "Authorization: Bearer $ARX_TOKEN" \
  $ARX_RPC/assets/alias/$ISSUER/fund-a | jq -r .ref)
echo $ASSET         # arxasset1...

The asset's chain-wide reference, arxasset1…, is derived from your address and the id you chose. Two issuers can both use fund-a without colliding. Claim topics are kyc, aml, accredited and jurisdiction. Jurisdictions are ISO 3166-1 alpha-2 codes.

2. Issue supply

arx send issue-asset $ASSET 1000

The 1,000 units land on the issuer. The rules apply to both ends of every transfer, so the issuer has to be attested too before it can send any.

3. Attest the issuer, then try the holder

# <subject> <identity reference> <claims> <jurisdiction>
arx send grant-attestation $ISSUER issuer-kyc-ref kyc CH

arx send transfer-asset $ASSET $HOLDER 100
action dropped: compliance check failed: arx1w86p… is not KYC'd/allowlisted

The holder has no attestation, so the chain drops the transfer. The reason above is the exact text the node returns. It's also in GET /actions/{signature} and in the block's effects.

4. Attest the holder in the wrong country

arx send grant-attestation $HOLDER holder-kyc-ref kyc DE
arx send transfer-asset $ASSET $HOLDER 100
action dropped: arx1w86p…'s jurisdiction (Some("DE")) is not among those arxasset1fsl4… permits

5. Fix the attestation, and the transfer goes through

arx send grant-attestation $HOLDER holder-kyc-ref kyc CH
arx send transfer-asset $ASSET $HOLDER 100      # "status": "confirmed"

curl -s -H "Authorization: Bearer $ARX_TOKEN" $ARX_RPC/accounts/$HOLDER/assets
# [{"symbol":"FUNDA", "balance":100, "transfer_eligible":true, "eligibility_reason":"eligible", …}]

A new grant replaces the old one completely, so a narrower grant can also take a claim away. Wallets can check eligibility_reason before sending. It reports the sender-side gate that would fail, such as missing_attestation, jurisdiction_not_allowed or holder_frozen.

Beyond these, issuers can cap holders, balance per holder and attestation age, freeze an asset or a single holder, lock amounts, and recover a lost holder's position. Each refusal comes with a specific message. The Console issuer pages cover the same flow with a UI, and the SDK has an encoder for each action (encodeRegisterAsset, encodeTransferAsset, encodeSetAssetLimits and the rest) to use with ArxiumRpc.sendAction.

Verify without a node

Arx Verify checks Arxium evidence on your own machine. It has no chain code and needs no node or network connection. You fetch a file from any RPC, ours included, and check it locally. Whoever served the file can't make a false one pass. The browser verifier runs the same code as the arx-verify CLI as a WASM module. Your file is read in the page and never uploaded.

Prove a holder's state: state proofs

A state proof is an account's current record, including its attestation, claims and jurisdiction, together with a Merkle path to a certified block. Fetch one for the holder from the walkthrough:

curl -s -H "Authorization: Bearer $ARX_TOKEN" \
  $ARX_RPC/accounts/$HOLDER/proof > proof.json

Drop proof.json on arxium.network/verify, or run arx-verify state-proof proof.json:

VALID
key: account:arx1w86p…
height: 31
block_hash: 0xe519…ec0a
value: {"attested_by":"arx1lzn2…","claims":["Kyc"],"jurisdiction":"CH", …}
certified: yes

VALID means this value is what the chain's state held under that key at that height. The check covers the Merkle path and the block's commitment to its certificate. It doesn't check the certificate's BLS signatures against the validator set, so confirm block_hash at that height with a source you already trust, such as the Explorer or a second RPC.

Prove a validator misbehaved: fault evidence

Validators write a signed evidence file whenever they see a fault. Any node serves its files:

curl -s -H "Authorization: Bearer $ARX_TOKEN" $ARX_RPC/evidence          # list of ids
curl -s -H "Authorization: Bearer $ARX_TOKEN" $ARX_RPC/evidence/<id> > evidence.json

The verdict tells you what the file proves:

• VALID, for equivocation or prevote/precommit equivocation. One validator signed two different blocks or votes at the same height and round. The verdict names its key as culpable_pubkey.
• UNRESOLVED, for execution_disagreement. A validator re-executed a block, got a different state root and signed a dissent. Both signatures are real, so the dispute did happen. The file can't say which side was wrong, so this isn't a verdict of guilt.
• Failure, which exits 1 in the CLI. The file is malformed or a signature doesn't check out. Treat it as no evidence at all.

An evidence file can come from any chain, including a throwaway one someone set up. Before relying on a VALID verdict, check that the file's genesis_hash matches the one arx query status printed for corechain-devnet. Most of the time /evidence is an empty list [], because nothing has gone wrong.

Devnet limits

• Resets happen. The devnet can restart from block 0, which wipes balances, assets, attestations and the attestor registry. Afterwards genesis_hash may change or stay the same, so don't rely on it alone to spot a reset. Height going backwards is the reliable sign. Claim from the faucet again, and ask for the attestor role again.
• Blocks every 2 seconds. Finality usually follows within a block or two. Poll /actions/{signature} rather than sleeping a fixed time.
• Zero-knowledge keys are a devnet setup. The proving and verifying keys for private claim proofs come from a devnet-only setup, not a public trusted-setup ceremony. ZK proofs on devnet are for testing integrations, not for trusting.
• Test value only. Devnet ARX and assets have no value. Don't reuse a devnet key anywhere else, and never put real personal data in an attestation's identity reference. Use an opaque reference.
• Things will change. Action formats and the SDK can change between devnet versions. Check arx --version against the latest package if a signature is suddenly rejected.

Stuck, or something on this page is wrong? Email contact@arxium.network.