Accounts

These endpoints expose the accounts your end-user customers have: bank accounts, IBANs, and on-chain wallets. Per-customer create + read endpoints hang off /customers/:id/accounts/* (every account is registered under exactly one customer, though an external bank account's holder can be a third party, such as the customer's supplier: see account holder). Org-wide read endpoints address accounts globally by UUID. Both surfaces are documented here.

All endpoints require auth: either an Api-Key: <key> (org-scoped, recommended) or Authorization: Bearer <access-token> (dashboard session). Curl snippets assume $SEISMIC_ORCHESTRATION_URL and $SEISMIC_ORCHESTRATION_API_KEY. See Auth for the full model.

Endpoints

Org-wide

GET /accounts, list every account the org has created, filterable by customer / kind / origin / currency / rail / status.
GET /accounts/:id, read a single account by UUID. Polymorphic: branch on kind to dispatch on the layout of details.
GET /accounts/:id/balance, the balance of a virtual account, kept in sync by Seismic as funds move, served from the stored balance (as_of says when it was last refreshed). The same fields also appear inline on the Account record.
POST /accounts/:id/balance/refresh, force a fresh upstream balance read, rate-limited to once a minute per account.
PUT /accounts/:id/liquidation, point an auto-liquidating virtual account at a different crypto account, or enable auto-liquidation on one created without it.
DELETE /accounts/:id/liquidation, turn auto-liquidation off.
DELETE /accounts/:id, delete an account.
GET /deposits, list deposits into the org's virtual accounts outside the order flow, each with its lifecycle status: the read-side twin of the deposit.status_changed webhook event.
GET /liquidations, list the auto-liquidations draining those virtual accounts, with their full lifecycle status.
GET /accounts/fiat/external/requirements, the fields an external bank account needs for a given currency and country.

Create an account (per-customer)

POST /customers/:id/accounts/fiat/virtual, provision a virtual (on-platform) bank account.
POST /customers/:id/accounts/fiat/external, register an existing bank account.
POST /customers/:id/accounts/crypto/virtual, provision a virtual (on-platform) crypto wallet.
POST /customers/:id/accounts/crypto/external, register an existing crypto wallet.

Read a customer's accounts

GET /customers/:id/accounts, list accounts attached to this customer.
GET /customers/:id/accounts/fiat/:account_id, retrieve a fiat account by id.
GET /customers/:id/accounts/crypto/:account_id, retrieve a crypto account by id.
GET /customers/:id/accounts/requests/:request_id, poll an AccountCreationRequest by id.
GET /customers/:id/accounts/requests?idempotency_key=…, look up a creation request by idempotency key.
GET /customers/:id/liquidation-destinations, which crypto accounts a new virtual account in a given currency may auto-liquidate to.

Account shape: `kind` + `shape` + `details`

Every Account carries an explicit kind ("fiat" or "crypto") and shape ("us", "uk", "iban", "swift", "cn_cnaps", "hk_fps", "sg_fast", "in_ifsc", "mx_clabe", "ar_cbu", "ph_bank", "thb_bank", "idr_bank", "ca_eft", "pk_iban", "ng_bank", "br_pix", "br_bank", "au_bsb", "co_bank", "evm", …). Together they determine the layout of details:

`kind`	`shape`	`details` layout
`fiat`	`us`	`{ account_number, routing_number, ach_routing_number, fedwire_routing_number, rtp_routing_number?, bic?, swift_account_number?, bank_name?, account_holder_name, bank_address, beneficiary_address?, swift_receiving_bank?, account_type? }`
`fiat`	`uk`	`{ sort_code, account_number, iban?, bank_name?, account_holder_name, bank_address }`
`fiat`	`swift`	`{ bic, account_number, phone?, tax_number?, bank_name, routing_number?, account_holder_name, bank_address }`
`fiat`	`iban`	`{ account_number, bic?, bank_code?, phone?, id_number?, id_type?, registration_number?, registration_type?, bank_name?, account_holder_name, bank_address }`
`fiat`	`cn_cnaps`	`{ account_number, cnaps_code, id_number, id_type?, registration_number?, registration_type?, bank_name?, branch_name?, account_holder_name, bank_address }`
`fiat`	`hk_fps`	`{ account_number, bic?, bank_name?, registration_number?, registration_type?, date_of_incorporation?, account_holder_name, bank_address }`
`fiat`	`sg_fast`	`{ account_number, bank_name, phone, id_number?, id_type?, registration_number?, registration_type?, relationship_to_debtor?, account_holder_name, bank_address }`
`fiat`	`in_ifsc`	`{ ifsc, account_number, phone?, id_number?, id_type?, registration_number?, registration_type?, relationship_to_debtor?, bank_name?, account_holder_name, bank_address }`
`fiat`	`mx_clabe`	`{ clabe, tax_number?, bank_name?, account_holder_name, bank_address }`
`fiat`	`ar_cbu`	`{ cbu, alias?, tax_number, phone, id_number?, id_type?, registration_number?, registration_type?, bank_name, account_holder_name, bank_address }`
`fiat`	`ph_bank`	`{ account_number, bank_name, phone?, registration_number?, registration_type?, date_of_incorporation?, relationship_to_debtor?, account_holder_name, bank_address }`
`fiat`	`thb_bank`	`{ account_number, bank_name, account_holder_name, bank_address }`
`fiat`	`idr_bank`	`{ account_number, bank_name, account_holder_name, bank_address }`
`fiat`	`ca_eft`	`{ institution_number, transit_number, account_number, bank_name, account_holder_name, bank_address }`
`fiat`	`pk_iban`	`{ iban, bank_name?, account_holder_name, bank_address }`
`fiat`	`ng_bank`	`{ account_number, bank_code, bank_name?, account_holder_name, bank_address }`
`fiat`	`br_pix`	`{ pix_key, pix_key_type, account_holder_name, bank_address }`
`fiat`	`br_bank`	`{ bank_code, agency, account_number, account_subtype, tax_number?, phone?, id_number?, id_type?, registration_number?, registration_type?, bank_name?, account_holder_name, bank_address }`
`fiat`	`au_bsb`	`{ bsb, account_number, account_holder_name, bank_address }`
`fiat`	`co_bank`	`{ bank_code, account_number, account_type, id_type, id_number, account_holder_name, bank_address }`
`crypto`	`evm`	`{ address }`

currency is singular on every account. rails is plural (fiat accounts settle over multiple rails, crypto accounts return a one-element array). The narrowing form a quote uses to pick a rail is { account, rails?, schemas? }. See Narrowing an account's rails.

Paying a `us` account from abroad

A domestic credit needs only the account number and a routing number. A payer sending from outside the US is asked for more:

swift_account_number — the account number to quote instead of account_number. Usually the same digits, since most issuing banks receive both legs at one number; a bank that receives the international leg through a correspondent reports the number at that bank here, which can be an IBAN.
swift_receiving_bank — { name?, address? } for the bank the international leg lands at. Usually the bank in bank_name, but it need not be: bank_name and bank_address describe where an ACH or domestic wire credit arrives.
beneficiary_address — the mailing address to quote for the account holder named in account_holder_name. One address per account: the issuing bank publishes it for the account itself, so it reads the same whichever rail the credit arrives on.
account_type — how the account is labeled on its payment instructions: "PERSONAL_CHECKING", "PERSONAL_SAVINGS", "BUSINESS_CHECKING" or "BUSINESS_SAVINGS". Treat it as open-ended — new values are added here as banks report them.

A virtual account reports these as soon as its bank details are issued. An account you registered from your own details reports only what you supplied, so one registered without an international route carries none of them. Addresses in these blocks are published as free-text lines, so expect line1 and line2 to be populated and the city / state / postal_code fields to be absent.